Run Marsad Locally Without Docker

Expected time: 45–120 minutes; Python model dependencies may take longer to install.

Outcome: The Web App, Model Server, Redis queues, and required workers run directly on your machine.

This path is useful when you need debugger access or fast process restarts. It requires more local configuration than the Docker Compose path, so keep a separate terminal open for every long-running process.

Run commands from the directory named in each section. Examples use PowerShell where commands differ by operating system.

1. Install the Prerequisites

Install these tools before continuing. Use the linked official instructions for your operating system rather than downloading installers from third-party sites.

Redis does not provide the same native installation path on every operating system. For a Windows setup without Docker, follow Redis's Windows guidance for WSL2 or its supported Windows-compatible option. Ask your onboarding partner which option the team uses before installing an alternative Redis implementation.

Verify the Installations

Open a new terminal after installation and run:

git --version
node --version
npm --version
yarn --version
python --version
psql --version
redis-cli --version

Expected results:

• node --version begins with v22.
• yarn --version begins with 1.22.
• python --version reports Python 3.10.x, unless the team approved another version.
• every command exits normally instead of reporting that it cannot be found.

Then start PostgreSQL and Redis using your operating system's service manager and verify that Redis accepts a local connection:

redis-cli ping

The response should be PONG. Also confirm that you have a local PostgreSQL database name, username, password, host, and port for PG_URL.

If MongoDB is required for your workflow, start it and verify it separately:

mongosh --eval "db.runCommand({ ping: 1 })"

Do not continue until the required commands are available and PostgreSQL and Redis accept local connections. If your starter task does not use temporary use-case storage, ask your onboarding partner whether MongoDB can be skipped.

2. Configure Local Environment Files

Create local files from the templates:

Copy-Item .\main\.env.example .\main\.env
Copy-Item .\model-server\.env.example .\model-server\.env

Treat example values only as placeholders. Replace database hosts, usernames, passwords, tokens, and provider settings with team-approved local development values; never assume a host in a template is safe to use.

For the direct-process layout, confirm these relationships:

The Web App's MODEL_API_TOKEN must match the Model Server's API_BEARER_TOKEN. The Model Server's MAIN_APP_API_KEY must match the credential expected by the Web App callback route. Obtain both pairs through the approved secret channel.

3. Share the Data Directory

The Web App and Model Server must see the same physical files. The repository layout normally uses main/shared-data/ and a link at model-server/shared-data.

First check whether the link or directory already exists. Do not replace it if it contains data.

Get-Item .\model-server\shared-data -ErrorAction SilentlyContinue

For a fresh Windows checkout where it is absent, create a directory junction from the repository root:

New-Item -ItemType Junction -Path ".\model-server\shared-data" -Target ".\main\shared-data"

On macOS or Linux, create the equivalent symbolic link from the repository root:

ln -s ../main/shared-data model-server/shared-data

4. Prepare and Start the Web App

From main/, install dependencies, generate Prisma code, and apply the checked-in migrations:

yarn install --frozen-lockfile
npx prisma generate
npx prisma migrate deploy
yarn dev

Seeding is optional and should use only an approved development database:

yarn prisma:seed

Leave the development server running. It should listen at http://localhost:3511.

5. Prepare and Start the Model Server

From model-server/, create and activate an isolated Python environment. In PowerShell:

python -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install -r requirements.txt
python .\app.py

app.py uses port 3531 by default. Keep this API terminal open.

On macOS or Linux, activate the environment with source .venv/bin/activate; the remaining Python commands are the same.

6. Start the Required Workers

Every worker must run from model-server/ with the same virtual environment and .env file as the API.

On Windows, open two more PowerShell terminals and run:

# Terminal: analysis and data-collection/report queues
.\.venv\Scripts\Activate.ps1
python .\worker_win.py

# Terminal: completion callbacks
.\.venv\Scripts\Activate.ps1
python .\notification_worker_win.py

The first worker consumes both tasks and data_collection_tasks; the second consumes notifications. If your workflow needs the dedicated tanbih_tasks queue, ask your onboarding partner for the supported local worker command before testing it.

On macOS or Linux, start standard RQ workers with the project environment active. Run each command in a separate terminal:

rq worker tasks data_collection_tasks --url redis://localhost:6379

rq worker notifications --url redis://localhost:6379

Use the URL configured in REDIS_DATABASE_URL if it differs from the example.

7. Verify the Process Set

Open http://localhost:3511, sign in with a safe development account, and inspect each terminal for startup errors. For an analysis job you should have, at minimum:

• PostgreSQL and Redis running;
• the Web App on port 3511;
• the Model Server on port 3531;
• a worker consuming tasks; and
• a worker consuming notifications.

Add MongoDB or the data-collection worker only when the exercised path needs them. The Windows combined worker already consumes data_collection_tasks.

Stop and Restart Safely

Stop application and worker processes with Ctrl+C in their own terminals. Stop infrastructure using the normal service manager for your operating system. Do not delete database contents or shared-data/ as part of a routine restart.

Checkpoint

You are ready to continue when the Web App loads, both application terminals are free of repeating startup errors, and the required workers report that they are listening on the expected queues.

Next: build Hello Marsad with Next.js →