Skip to main content

​
Prerequisites

Before you begin, make sure you have the following installed:

​
Clone and enter the environment

git clone https://github.com/MalboxSandbox/malbox.git
cd malbox
Start the development environment: 
nix develop
This automatically sets up:
  • Rust stable toolchain (rustc, cargo, clippy, rustfmt, rust-analyzer)
  • PostgreSQL 16
  • Node.js and pnpm
  • C/C++ build tools (cmake, gcc, clang 18)
  • Windows cross-compilation toolchain (MinGW)
  • Infrastructure tools (packer, ansible)
  • Protobuf compiler and codegen tools
  • Pre-commit hooks (cargo-check, clippy, rustfmt)
The first run takes a while as Nix downloads and builds all dependencies. Subsequent runs are near-instant.
The flake also provides specialized sub-shells if you only need a subset of tools: 
nix develop .#backend   # Rust toolchain, PostgreSQL, build tools
nix develop .#frontend  # Node.js, pnpm
nix develop .#docs      # Node.js (for Mintlify)
Each subdirectory (back-end/, front-end/, docs/) includes an .envrc file that activates the appropriate sub-shell automatically. If you use direnv, just cd into the directory you want to work in.

​
Database

process-compose manages PostgreSQL 16. Start it from the back-end/ directory: 
cd back-end
process-compose up
This initializes the data directory, starts PostgreSQL, and creates the malbox_db database automatically. The DATABASE_URL environment variable is set for you automatically by the flake:
SettingValue
Host127.0.0.1
Port5432
Databasemalbox_db
Userpostgres
DATABASE_URLpostgres://postgres@localhost:5432/malbox_db
To run pending database migrations: 
cd back-end
sqlx migrate run

​
Running the backend

Make sure PostgreSQL is running via process-compose up first (see Database), then from the back-end/ directory: 
cd back-end
cargo run -p malbox -- daemon start
The daemon starts an HTTP server on http://127.0.0.1:8080.

​
Running the frontend

In a separate terminal: 
cd front-end
cp .env.example .env
pnpm install
pnpm dev
The dev server starts at http://localhost:5173. It proxies API requests to the backend at the URL configured in .env: 
# .env
MALBOX_API_URL=http://127.0.0.1:8080
BODY_SIZE_LIMIT=0

​
Running the docs

In a separate terminal: 
cd docs
npx mintlify@latest dev
The docs site starts at http://localhost:3000.

​
Daily workflow

​
Running tests

# Run the test suite (uses cargo-nextest)
cd back-end
cargo nextest run

# Run doctests separately (nextest doesn't support them)
cargo test --doc

​
Formatting and linting

Pre-commit hooks run cargo-check, clippy, and rustfmt automatically on every commit. You can also run them manually: 
# Backend
cd back-end
cargo fmt
cargo clippy

# Frontend
cd front-end
pnpm lint
pnpm format

​
Type checking the frontend

cd front-end
pnpm check          # one-off
pnpm check:watch    # continuous

​
Database migrations

Create a new migration: 
cd back-end
sqlx migrate add <migration_name>
This creates a new SQL file in the migrations directory. After writing your migration, run it: 
sqlx migrate run
After changing queries, update the offline query cache so CI builds work without a live database: 
cargo sqlx prepare

​
Building Rust documentation

cd back-end
cargo doc --no-deps --document-private-items

​
Pre-commit hooks

The Nix flake installs Git hooks that run on every commit:
  • cargo-check - verifies the project compiles
  • clippy - catches common mistakes and style issues
  • rustfmt - enforces consistent formatting
Do not skip these hooks with --no-verify. If a hook fails, fix the issue before committing.

​
Troubleshooting

​
nix develop fails or hangs

Make sure Nix is installed correctly and the Nix daemon is running: 
nix --version
If you see errors about missing flake inputs, try: 
nix flake update

​
Database connection refused

PostgreSQL may not be running. Check its status: 
pg_isready -h 127.0.0.1 -p 5432
If it reports no connection, make sure process-compose up is running in the back-end/ directory (see Database).

​
SQLx compile errors about missing queries in CI

If you see SQLx compile-time errors, make sure the offline query cache is up to date: 
cd back-end
cargo sqlx prepare
For CI or when you don’t have a running database, set SQLX_OFFLINE=true: 
SQLX_OFFLINE=true cargo build

​
Frontend can’t reach the backend

Make sure:
  1. PostgreSQL is running (process-compose up in back-end/)
  2. The backend is running (cargo run -p malbox -- daemon start)
  3. Your .env file has the correct MALBOX_API_URL (default: http://127.0.0.1:8080)