Quick Start

This guide takes you from zero to a running full-stack application in under five minutes. By the end, you will have a Rust API, a Next.js public website, and a Next.js admin dashboard — all running locally over HTTPS with a seeded database and a default admin account.

Create a New Application

Run the forge new command to generate your project:

forge new --name=myapp

FORGE will prompt you to confirm a few options, then generate the entire project. For a fully customized setup, pass all options explicitly:

forge new \
  --name=myapp \
  --backend=rust \
  --frontend=nextjs \
  --template=base \
  --auth=email_password \
  --default-lang=en \
  --languages=en,ar

Interactive mode

Prefer a guided setup? Use forge new --interactive to walk through each option with descriptions and defaults.

What Gets Generated

After the command completes, your project directory will contain:

myapp/
├── apps/
│   ├── api/              # Rust (Axum) backend API
│   ├── web/              # Next.js public website
│   └── admin/            # Next.js admin dashboard
├── infra/
│   ├── docker/           # Docker Compose and Dockerfiles
│   ├── caddy/            # Caddyfile reverse proxy config
│   └── certs/            # SSL certificates (auto-generated)
├── database/
│   ├── migrations/       # Versioned SQL migrations
│   └── seeders/          # Default data (admin user, roles, permissions)
└── forge.yaml            # Project configuration

FORGE also performs these setup steps automatically:

1. Generates SSL certificates using mkcert for your local domains
2. Adds hosts entries to /etc/hosts for myapp.test, admin.myapp.test, and api.myapp.test
3. Installs dependencies — runs cargo build and npm install
4. Runs database migrations — creates all tables in PostgreSQL
5. Seeds the database — inserts default admin user, roles, permissions, and translations

Hosts file modification requires elevated permissions

FORGE will ask for your password (via sudo) to add entries to /etc/hosts. If you prefer to manage hosts manually, use the --no-hosts flag and add the entries yourself:

127.0.0.1   myapp.test
127.0.0.1   admin.myapp.test
127.0.0.1   api.myapp.test

Start the Development Server

Navigate to your project and start all services:

cd myapp
forge serve

This single command starts:

Service	URL	Description
Web App	https://myapp.test	Public-facing Next.js website
Admin Panel	https://admin.myapp.test	Admin dashboard (Next.js)
API Server	https://api.myapp.test	Rust backend API
API Docs	https://api.myapp.test/docs	Swagger UI documentation
PostgreSQL	localhost:5432	Database (via Docker)
Redis	localhost:6379	Cache store (via Docker)

What forge serve does under the hood

It starts Docker containers for PostgreSQL, Redis, and Caddy, then launches the Rust API server and both Next.js development servers in parallel. Caddy handles reverse proxying and SSL termination for all three domains.

Log in to the Admin Panel

Open your browser and navigate to:

https://admin.myapp.test

Sign in with the default administrator credentials:

Field	Value
Email	admin@myapp.test
Password	admin123

Change the default password immediately

The default credentials are for development convenience only. Change the admin password before deploying to any shared or production environment.

Once logged in, you will see the admin dashboard with:

• Dashboard — Overview statistics and quick actions
• Users — Create, edit, and manage user accounts
• Roles — Define roles and assign permissions
• Content — Create and manage translatable content pages
• Menus — Build dynamic navigation menus for the web app
• Media — Upload and manage files and images
• Settings — Application-wide configuration
• Audit Log — Track all administrative actions

Explore the Web Application

Open the public website at:

https://myapp.test

The web application includes:

• Home page with dynamic content pulled from the CMS
• User registration and login
• User profile management (protected route)
• Language switcher with RTL support (if multiple languages are configured)
• Dynamic navigation driven by menus created in the admin panel
• Content pages accessible by slug (e.g., https://myapp.test/about)

Explore the API

The API server provides a complete REST API. Open the interactive documentation at:

https://api.myapp.test/docs

You can also test endpoints directly:

Login

curl -X POST https://api.myapp.test/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "admin@myapp.test",
    "password": "admin123"
  }'

List Users (authenticated)

# Use the token from the login response
curl https://api.myapp.test/api/v1/admin/users \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Get Public Content

curl https://api.myapp.test/api/v1/contents/home

The API response format is consistent across all endpoints:

{
  "success": true,
  "message": "Users retrieved successfully",
  "data": {
    "items": [...],
    "pagination": {
      "page": 1,
      "per_page": 15,
      "total": 42,
      "total_pages": 3
    }
  }
}

Project Commands

Here are the most commonly used commands during development:

# Start all services
forge serve

# Run database migrations
forge migrate:run

# Reset database and re-run all migrations + seeders
forge migrate:fresh

# Seed the database
forge seed

# Generate a new model with migration, handler, and service
forge make:model Post

# Add a new language
forge lang:add fr

# View container logs
forge docker:logs

# Stop all services
forge docker:down

What to Do Next

Now that your application is running, explore the deeper guides:

• Configuration — Customize forge.yaml for your project needs
• Directory Structure — Understand how the generated code is organized
• Contract-First Design — Learn how FORGE's architecture enables extensibility
• Backend Overview — Dive into the Rust API layer
• Frontend Overview — Explore the Next.js applications
• Content Management — Create and manage CMS pages