Run Marsad Locally with Docker

Expected time: 30–90 minutes; the first model image build can take longer.

Outcome: The Web App loads locally and the services needed for asynchronous jobs are running.

Docker Compose is the recommended onboarding path because it matches the integrated service layout. Run these commands from the Marsad repository root—the directory containing main/, model-server/, and docker-compose.yml—not from marsad-docs/.

If you need to run each dependency and application process directly, use Run Locally Without Docker instead.

1. Prepare Development Configuration

Confirm that the team-provided development environment files exist for the services you will run. Use committed example files to understand variable names, but obtain secret values through the team's approved channel.

Before continuing, check that:

• the Web App database setting points to an approved development database;
• the Web App and Model Server credentials match their paired values;
• every service uses the same Redis instance; and
• both application containers resolve the shared directory at /app/shared-data.

Do not print environment files into chat, terminal recordings, issues, or pull requests.

2. Build and Start the Stack

docker compose -f docker-compose.yml up -d --build

The first build may download large model dependencies. Let it finish before diagnosing missing containers.

3. Inspect Service State

docker compose -f docker-compose.yml ps

For the standard analysis path, confirm that these are running:

• main-app on http://localhost:3511;
• model-server on port 3531;
• redis;
• model-worker, which consumes tasks; and
• model-notification-worker, which delivers callbacks.

Collection and report work also needs model-data-collection-worker. Some analysis capabilities use the dedicated model-tanbih-worker.

4. Inspect Logs Safely

If a service is restarting or unhealthy, inspect only the relevant recent logs:

docker compose -f docker-compose.yml logs --tail 100 main-app
docker compose -f docker-compose.yml logs --tail 100 model-server

Add the affected worker service name when debugging a queued job. Redact tokens, private prompts, uploaded content, and user data before sharing any log excerpt.

5. Open the Web App

Visit http://localhost:3511 and sign in with the safe development account provided by your team. Confirm that the first authenticated page renders without an error.

Stop the Stack

When you finish working, stop the Compose services from the repository root:

docker compose -f docker-compose.yml down

This removes the local containers and network but does not intentionally erase named volumes or your shared-data directory. Do not add --volumes unless you have explicitly decided to remove local persisted state.

Checkpoint

You are ready to continue when the Web App loads, Compose reports the required API and worker services as running, and recent logs contain no repeating startup failure.

Next: build Hello Marsad with Next.js →