Installation

This guide walks you through cloning the repository, starting the infrastructure, and installing dependencies.

1. Clone the Repository

git clone https://github.com/dominikdorfstetter/forja.git
cd forja

2. Start Docker Services

Forja ships with a docker-compose.dev.yaml that runs PostgreSQL 16, Redis 7, and pgAdmin:

docker compose -f docker-compose.dev.yaml up -d

This creates three containers:

Container	Service	Port
forja-db	PostgreSQL 16	5432
forja-redis	Redis 7	6379
forja-pgadmin	pgAdmin 4	5050

Verify they are running:

docker ps --format "table {{.Names}}\t{{.Status}}\t{{.Ports}}"

tip

You can also use the dev script, which waits for health checks automatically:

./scripts/dev-start.sh

3. Configure the Backend

Copy the example environment file and adjust values as needed:

cd backend
cp .env.example .env

The defaults work out of the box with the Docker services. The most important variable is already set:

DATABASE_URL=postgres://forja:forja@localhost:5432/forja

If you have a Clerk account, add your keys now (see Configuration for the full variable reference):

CLERK_SECRET_KEY=sk_test_...
CLERK_PUBLISHABLE_KEY=pk_test_...
CLERK_JWKS_URL=https://your-clerk-domain.clerk.accounts.dev/.well-known/jwks.json
SYSTEM_ADMIN_CLERK_IDS=user_...

Return to the project root:

cd ..

4. Install Admin Dependencies

cd admin
npm install
cd ..

5. Quick Start with Dev Scripts

Forja includes convenience scripts in the scripts/ directory. The most common one starts everything at once:

# Start Docker infra + backend + admin in one command
./scripts/dev-start.sh --all

Other options:

./scripts/dev-start.sh              # Docker infra only
./scripts/dev-start.sh --backend    # Infra + Rust backend
./scripts/dev-start.sh --admin      # Infra + admin dashboard

Available Dev Scripts

Script	Purpose
./scripts/dev-start.sh	Start development environment
./scripts/dev-stop.sh	Stop all Docker services
./scripts/dev-seed.sh	Run migrations and seed the database
./scripts/dev-build.sh	Build backend and admin for production
./scripts/dev-test.sh	Run test suites
./scripts/dev-clean.sh	Remove containers, volumes, and build artifacts
./scripts/dev-logs.sh	Tail Docker container logs
./scripts/dev-status.sh	Show status of all services

Project Structure

After cloning, your directory should look like this:

forja/
├── admin/                 # React admin dashboard (Vite + MUI)
├── backend/               # Rust API server (Rocket 0.5 + SQLx)
│   ├── migrations/        # SQLx database migrations
│   ├── scripts/           # Backend-specific scripts (seed, init)
│   ├── src/               # Rust source code
│   └── .env.example       # Environment variable template
├── templates/
│   └── astro-blog/        # Astro frontend template
├── website/               # Docusaurus documentation site
├── scripts/               # Top-level dev scripts
└── docker-compose.dev.yaml

Next Steps

Continue to First Run to run migrations, seed the database, and verify your setup.