HXCKR

HXCKR is a modular Learning Management System (LMS) designed to facilitate bitcoin technical education through structured challenges and exercises. The motivation behind this project is to provide a scalable and flexible platform for learning technical concepts through hands-on experience.

Project Structure

The project is organized into three main layers:

• Domain Layer: Core business logic, including entities, value objects, and domain services. This layer is independent of external frameworks and services.
• Application Layer: Orchestrates use cases by coordinating between the domain layer and external services. It defines the flow of data but does not contain business logic.
• Infrastructure Layer: Implements integrations with external systems, such as databases, APIs, and web frameworks. This layer contains the adapters that interact with the outside world.

Features

• Challenges and Exercises: Users can engage in structured challenges that consist of multiple exercises or tasks, each designed to teach specific technical concepts.
• Submissions and Validation: The system supports user submissions, which are validated against predefined test cases using server-side test runners.
• Progress Tracking: Users' progress is tracked across challenges, with achievements and leaderboard rankings displayed for motivation.
• Extensible Design: The system is designed to be modular and easily extensible, with clear separation of concerns.
• Self-Deployable: The goal is to ensure that the infra can be replicated and used by bitcoin education platforms while managing the instance themselves.

Getting Started

Prerequisites

• Rust and Cargo are required to build and run the application (this is provided via Nix). You can also install them globally using rustup.
• PostgreSQL is used as the database for this project (this is provided via docker compose using Nix flakes).
• Nix flake is used to manage the dependencies in the development environment. You can install it following the instructions here.
• Docker is used to manage the database. You can install it following the instructions here.
• Diesel CLI is used to manage the database schema (this is provided via Nix flakes).

1 Clone the Repository:

git clone https://github.com/extheoisah/hxckr-core.git
cd hxckr-core

2.Setup the Development Environment:

Important

Before running the following command, make sure you have nix-package manager installed on your system. If not, you can install it following the instructions provided here. You should configure your nix to use flake by setting your ~/.config/nix/nix.conf file to use flake as follows: experimental-features = nix-command flakes

then run the following command to install the dependencies and setup the development environment in the project directory:

 nix develop

Alternatively, you can run the following command to install the dependencies and setup the development environment:

nix develop --experimental-features 'nix-command flakes'

3.Run the Application: If you are running the application for the first time, please follow the instructions here to setup the database. Then run the following command to start the application:

cargo run

The server should be running on http://localhost:4925. To check if the server and database connection is working fine, run:

curl --location 'http://localhost:4925/api/health'

You should get a 200 response. If not, please review the steps above and in the contributing guide again or reach out to one of the maintainers for assistance.

Websocket Server

The server also has a websocket server running on ws://localhost:4925/ws. This websocket server is used to send and receive messages between the server and the clients (the hxckr frontend). The websocket server supports the following message types:

• Message::Text(String): A text message.
• Message::Binary(Vec<u8>): A binary message.

For development purposes, we have provided a simple websocket library (wscat) which has been installed in the nix shell. The websocket is behind a middleware that authenticates the user using the session token similar to how the API works. To connect to the websocket server, run the following command:

wscat -c ws://localhost:4925/ws -H "x-session-token: <session_token>"

You should see the following output:

Connected (press CTRL+C to quit)
>

You can now send and receive messages to and from the server. You can also use Postman to test the websocket server.

Pub / Sub

The server has a pub/sub system that is used to receive real time events from the git service and test runners, and send real-time messages to the clients. The pub/sub system is built using the Rabbimq message broker. The pub/sub system is used to send real-time messages to the clients such as the challenge results, the leaderboard, etc. Only the git service and test runners will publish messages to the queue, while the clients and the server will subscribe to the queue to receive messages.

Contributing

Contributions are welcome! Please open an issue or submit a pull request. For more details, please refer to the CONTRIBUTING.md file.

Docker

Building the Docker Image

To build the Docker image locally:

1. Ensure you have Docker installed on your machine.

2. Navigate to the project root directory in your terminal.

3. Build the Docker image:

   docker build -t hxckr-core:local .

Running the Docker Container

To run the Docker container:

docker run -p 8080:80 -e DATABASE_URL=postgres://real_username:real_password@real_host/real_db hxckr-core:local

Publishing Docker Images

This project uses GitHub Actions to automatically publish Docker images to DockerHub. If you fork this repository, you'll need to set up the publishing process:

1. Create a DockerHub account if you don't have one.
2. Create a new repository on DockerHub for your images.
3. In your GitHub repository settings, add the following secrets:
   • DOCKERHUB_USERNAME: Your DockerHub username
   • DOCKERHUB_TOKEN: A DockerHub access token (create this in your DockerHub account settings)
4. Update the GitHub Actions workflow file (.github/workflows/docker-publish.yml) with your DockerHub repository name.

The workflow will build and push a new Docker image on each push to the main branch and when a new release is created.

Development

Please refer to the CONTRIBUTING.md file for more details on how to contribute to this project.

Spell Checking

To maintain consistent spelling across the project, we use the typos crate for spell checking. Follow these steps to run the spell check locally:

1. Ensure you are in the nix shell.

2. Install the typos crate:

   cargo install typos-cli

3. Run the spell check from the root of the project:

   typos

4. If there are any spelling issues, typos will output them to the console.

5. Fix any misspellings in your code, or add project-specific terms to the [default.extend-words] list in typos.toml if they are correct for this project.

Note: Running this check locally before committing can help catch spelling errors early and keep the GitHub Actions checks passing.