Environment Setup

This page is for source development and local debugging. For production or single-host private deployment, use the Docker Compose release package in Deployment.

This guide assumes a Linux/macOS shell by default. The recommended development setup is split: run dependency services with Docker Compose, then run backend and frontend processes directly on the host. This makes code debugging, log inspection, frontend changes, and individual Worker processes easier.

1. Processes and ports

Local ASP development involves three backend process types:

Process	Default Port	Responsibility
WSGI / Django	8000	Optional Django REST API entrypoint that handles /api/ directly.
ASGI / Django + WebSocket	8001 (adjustable)	Default Vite proxy target that handles both /api/ and /ws/.
Workers	—	Background tasks: Module consumption, Case analysis, Playbook execution, ELK polling, and Dashboard caching.

Routing:

/api/*    -> ASGI / Django (Vite default)
/ws/*     -> ASGI / WebSocket

In production, the ASGI container uses internal port 8001. If Redis Stack UI also uses 8001 locally, choose another free ASGI port and update both the /api and /ws proxies in frontend/vite.config.ts.

2. Start dependency services

Use development/docker to start PostgreSQL, Redis Stack, and RustFS:

cd /path/to/agentic-soc-platform/development/docker
cp .env.example .env
docker compose up -d

Available services:

Service	Address	Purpose
PostgreSQL	localhost:5432	Backend database.
Redis	localhost:6379	Cache and Redis Stream.
Redis Stack UI	http://localhost:8001	Redis web management UI.
RustFS S3 API	http://localhost:9000	S3-compatible API for attachments and avatars.
RustFS Console	http://localhost:9001	RustFS web console.

If a port is already in use, adjust development/docker/.env or the Compose port mapping before starting dependency services.

3. Configure backend .env

Enter backend and create a local .env from the example:

cd /path/to/agentic-soc-platform/backend
cp .env.example .env

At minimum, make sure these values match development/docker/.env:

DJANGO_SECRET_KEY=dev-secret-key
DJANGO_DEBUG=true
DJANGO_ALLOWED_HOSTS=*

POSTGRES_DB=asp
POSTGRES_USER=postgres
POSTGRES_PASSWORD=asp-dev-postgres-password
POSTGRES_HOST=localhost
POSTGRES_PORT=5432

REDIS_HOST=localhost
REDIS_PORT=6379
REDIS_DB=1
REDIS_PASSWORD=asp-dev-redis-password

RUSTFS_ENDPOINT_URL=http://localhost:9000
RUSTFS_ACCESS_KEY=asp
RUSTFS_SECRET_KEY=asp-dev-rustfs-password
RUSTFS_BUCKET=asp
RUSTFS_REGION=us-east-1

These values are for local development only. Production must use random secrets and controlled passwords.

4. Initialize backend

Install dependencies, apply migrations, and create an administrator:

uv sync
.venv/bin/python manage.py migrate
.venv/bin/python manage.py createsuperuser

Common checks:

.venv/bin/python manage.py check
.venv/bin/python manage.py test

Backend dependencies are managed by uv. Prefer backend/.venv/bin/python for management commands.

5. Start backend API

The common option is Django development server:

.venv/bin/python manage.py runserver 0.0.0.0:8000

After startup:

• API: http://localhost:8000/api/

For a setup closer to production, use Gunicorn:

.venv/bin/gunicorn asp.wsgi:application --bind 0.0.0.0:8000 --reload

6. Start ASGI / WebSocket

The ASGI process provides both the Django HTTP API and realtime event WebSocket, and is Vite's default backend:

.venv/bin/uvicorn asp.asgi:application --host 0.0.0.0 --port 8001 --reload

ASGI routes:

/ws/*  -> Realtime event WebSocket
/api/* -> Django HTTP API
/      -> Django fallback

If 8001 is already used by Redis Stack UI, choose another free port and update both the frontend /api and /ws proxies.

7. Start Workers

Start background processes as needed:

.venv/bin/python manage.py run_agentic_module_worker
.venv/bin/python manage.py run_agentic_case_analysis_worker
.venv/bin/python manage.py run_agentic_playbook_worker
.venv/bin/python manage.py run_elk_action_worker
.venv/bin/python manage.py run_dashboard_cache_worker

Worker	Purpose
run_agentic_module_worker	Consumes Redis Stream and runs Modules to generate Cases / Alerts / Artifacts.
run_agentic_case_analysis_worker	Runs Case AI analysis tasks.
run_agentic_playbook_worker	Runs user-triggered Playbooks.
run_elk_action_worker	Polls alerts from the ELK Action Index.
run_dashboard_cache_worker	Periodically generates the Dashboard 24h, 7d, and 30d caches.

Dashboard requires run_dashboard_cache_worker to generate its first cache; without it, the Dashboard returns 503. You can omit this worker when developing other frontend list pages.

8. Start frontend

Enter frontend, install dependencies, and start Vite:

cd /path/to/agentic-soc-platform/frontend
pnpm install
pnpm dev

Default URL:

http://localhost:5173

Default Vite proxy:

http://localhost:5173/api/*  ->  http://localhost:8001/api/*
ws://localhost:5173/ws/*     ->  ws://localhost:8001/ws/*

If ASGI uses a different port, update vite.config.ts accordingly:

server: {
  proxy: {
    '/api': { target: 'http://localhost:8002', changeOrigin: true },
    '/ws': { target: 'ws://localhost:8002', ws: true },
  },
}

Frontend changes do not need npm build unless build validation is explicitly requested.

9. Frontend-backend request flow

Development:

Browser (localhost:5173)
  -> Vite proxy
    -> /ws/*     -> ASGI (localhost:8001 or custom port)
    -> /api/*    -> ASGI / Django (localhost:8001 or custom port)

Production:

Browser (443)
  -> Nginx
    -> /ws/*     -> ASGI (asp-asgi:8001)
    -> /api/*    -> WSGI / Django (asp-web:8000)
    -> /*        -> Frontend static files

10. Custom directory

During source development, backend/custom/ mirrors the custom/ directory in the Compose release package:

backend/custom/
  modules/
  playbooks/
  data/
    modules/
    siem/
    playbooks/
  requirements.txt

• backend/custom/modules/: Custom Modules.
• backend/custom/playbooks/: Custom Playbooks.
• backend/custom/data/siem/: Custom SIEM YAML.
• backend/custom/data/playbooks/: Custom Playbook prompts.
• backend/custom/requirements.txt: Extra Python packages required by custom code.

To test custom dependencies, install them into a local custom package directory and add it to PYTHONPATH:

mkdir -p .custom-packages
uv pip install --python .venv/bin/python --target .custom-packages -r custom/requirements.txt
export PYTHONPATH="$(pwd)/.custom-packages:$(pwd)/custom"

After changing scripts or YAML files, use Refresh / Validate in the ASP frontend Custom Console.

Next Steps

• Mock Data — Generate workspace data or SIEM test logs.
• Custom Console — Refresh and validate locally loaded custom definitions.
• Module Development — Write custom alert processing Modules.
• Playbook Development — Write automation tasks triggered from Cases.