Installation

A complete installation guide for development and production environments. For a fast path, start with the Quick Start.

Prerequisites

Required software

• Rust 1.88+ — install via rustup:

  curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
  source ~/.cargo/env

• Docker & Docker Compose — for database services
• Node.js 20+ — for frontend development
• PostgreSQL 16+ — if not using Docker
• Redis 7+ — optional; if not using Docker

Development tools

# Auto-reload during development
cargo install cargo-watch

# Database migrations (rustls avoids an OpenSSL dependency)
cargo install sqlx-cli --no-default-features --features rustls,postgres --locked

Frontend npm dependencies are installed automatically by make setup.

Step-by-step installation

1. Clone and configure

git clone https://github.com/atomicjolt/atomic-forge.git
cd atomic-forge/atomic-reactor
cp .env.example .env

Edit .env with your settings. See Configuration for details.

2. Start database services

docker-compose up -d postgres redis
docker-compose ps

3. Initialize the database

make db-migrate

# Optional: seed with test data
make db-seed

4. Build and start

cargo build
make dev
# Access at http://localhost:8080

Production installation

Docker production build

docker build -t atomic-reactor .

docker run -d \
  --name atomic-reactor \
  -p 8080:8080 \
  -e DATABASE_URL=postgresql://... \
  -e SESSION_SECRET=... \
  -e ENCRYPTION_MASTER_KEY=... \
  -e JWT_SECRET=... \
  atomic-reactor

See Configuration for the full list of environment variables and how to generate the required secrets.

Verification

After installation, verify everything is working:

1. Health check: curl http://localhost:8080/health
2. Database connection: make db-console
3. Metrics: curl http://localhost:8080/metrics

Troubleshooting

Database connection failed

docker-compose ps             # check PostgreSQL is running
psql $DATABASE_URL            # verify the connection string
make db-reset                 # reset the database

Build failures

cargo clean
cargo update
cargo sqlx prepare            # rebuild the SQLx cache

Port conflicts

If port 8080 is in use, change it in .env:

PORT=8555