Skip to main content

Install Argus

This page installs the Argus site node with its built-in edge node, then shows how to add edge nodes on other hosts and how to install a site that has no internet access.

Check the requirements first.

Before you start​

You need:

  • A site node host that meets the requirements.
  • The Argus release from VoisX. It contains the Compose files (docker-compose.yml, docker-compose.gpu.yml, docker-compose.test-rtsp.yml, and the optional docker-compose.lan.yml, docker-compose.onvif-macvlan.yml and docker-compose.onvif-host.yml), the configuration template .env.example, the edge-node/, site-node/ and caddy/ folders, the database schema and migrations in db/, and helper scripts in scripts/.
  • Internet access on the host while you build and download models. Without it, follow Offline sites.

Run every command on this page from the release folder.

1. Copy the release to the site node​

Copy the release to a folder on the site node, for example /opt/argus, and go to it:

cd /opt/argus

2. Set the required secrets​

All settings live in one file, .env, in the release folder. Keep it from release to release. Start from the template:

cp .env.example .env
chmod 600 .env

Then fill in the required values. Each one has no default, and the services that need it refuse to start without it:

SettingWhat it is
SESSION_SECRETSigns dashboard sessions. At least 32 characters, and not a placeholder, or site-api doesn't start.
LIVE_STREAM_SECRETShared by site-api and every edge node. Signs the short-lived links for live video.
POSTGRES_PASSWORDPassword of the site database. POSTGRES_USER and POSTGRES_DB default to site.
REDIS_PASSWORDPassword of the Redis event streams.
S3_ACCESS_KEY and S3_SECRET_KEYCredentials of the clip storage (SeaweedFS). S3_BUCKET defaults to clips.

To generate random values, run this once per secret:

python3 -c "import secrets; print(secrets.token_hex(32))"

Use letters and digits only. The database and Redis passwords are part of connection URLs.

Edge node credentials​

Edge nodes don't need the site's own passwords. Give them their own, limited credentials instead. Set these in .env too, each to a different random value:

SettingWhat the edge nodes can do with it
EDGE_DB_PASSWORDLog in to the database as argus_edge. This user can only read the camera assignments and detection settings, and record the node's check-ins. It can't read users, sessions, the audit log, events or alerts, and it can't change another node's live video address.
EDGE_REDIS_PASSWORDLog in to Redis as argus-edge. This user can only publish detections and clip notices, and take clip requests. It can't read other nodes' detections.

Edge nodes get no clip storage credentials at all. With each clip request, the site sends an upload link for that one clip, valid for 10 minutes. An edge node can upload that clip, and nothing else: it can't read, list or delete clips. The site checks each upload, which must be an MP4 file of at most 200 MB, before it attaches the clip to the event. It then moves the clip to a place no edge node has a link for, so a clip, once attached, can't be replaced. A camera has at most 20 open upload links at a time.

Argus creates these users from .env every time it starts, so to change a password, change it in .env and run docker compose up -d. The built-in edge node uses them automatically.

If you leave them empty, the edge nodes use the site's own passwords and log a warning. This is supported for one more release only.

An edge node still needs some trust. With its credentials, it can:

  • see every camera's address, including camera passwords, because it connects to the cameras;
  • report detections for any camera;
  • upload a clip for any open clip request of another node while the link is valid, before that node does;
  • take another node's live video address offline until that node checks in again;
  • delete event messages that the site hasn't processed yet, or give event messages IDs far in the future. The second doesn't stop event delivery, but System Health then shows "event stream ID poisoned". See Repair event stream IDs.

Run edge nodes on hosts you control.

Argus also takes away two default database rights, temporary tables and connecting, from every user except its own on the Argus database. Other databases on the same PostgreSQL server are not changed.

Also set these two lines in .env, so that every docker compose command on these pages uses the right files and keeps the same volume names:

.env
COMPOSE_PROJECT_NAME=argus
COMPOSE_FILE=docker-compose.yml

COMPOSE_PROJECT_NAME fixes the names of the images and volumes, for example argus_pgdata.

Password reset email​

So that users can reset a forgotten password themselves, set PUBLIC_BASE_URL to the dashboard's address, for example PUBLIC_BASE_URL=https://argus.example.com, and either the SMTP_* settings or, after the start, an email channel for account emails in the dashboard. You can also do this later. See Set up password reset email.

Site timezone​

Set SITE_TIMEZONE to the IANA name of the site's timezone, for example Asia/Dubai or Europe/London. Detection profile schedules and workflow schedules are wall-clock times at the site, and are evaluated in this timezone. Reports also group days and hours in this timezone. If you leave it empty, they use UTC. An invalid name is logged as a warning, and UTC is used.

warning

Set the secrets before you start Argus for the first time. PostgreSQL and the clip storage keep the credentials they were first started with.

3. Choose the HTTPS certificate​

Argus serves the dashboard, the API, clip playback and live video over HTTPS only, through the caddy container. It is the only container with published ports: 443 for HTTPS, and 80, which only redirects to HTTPS. To use other ports, set HTTPS_PORT and HTTP_PORT. To listen on one network interface only, set HTTPS_BIND_ADDRESS to its IP address.

Pick one certificate mode in .env:

ModeSet in .envCertificate
Site certificate authority (default)NothingCaddy runs its own certificate authority and issues a certificate for the host name or IP address the browser uses. Optionally limit the names with SITE_HOSTS, for example SITE_HOSTS=argus.lan,192.168.1.50.
Public DNS nameSITE_DOMAIN=argus.example.com, and optionally ACME_EMAILAn automatic certificate from Let's Encrypt or ZeroSSL. The DNS name must point at the site node, and ports 80 and 443 must be reachable from the internet.
Your own certificateTLS_CERT_FILE=/certs/fullchain.pem and TLS_KEY_FILE=/certs/privkey.pemPEM files that you put in the certs/ folder of the release. SITE_DOMAIN or SITE_HOSTS can name the hosts.

If both a certificate file and SITE_DOMAIN are set, the certificate file wins.

Trust the site certificate authority​

In the default mode, browsers show a warning until each operator's computer trusts the site's certificate authority once. After the first start (step 5), export its root certificate:

docker compose cp caddy:/data/caddy/pki/authorities/local/root.crt ./argus-root-ca.crt

Install argus-root-ca.crt as a trusted root on each computer that opens the dashboard:

SystemHow
Windowscertutil -addstore Root argus-root-ca.crt, or double-click the file and place it in Trusted Root Certification Authorities.
macOSsudo security add-trusted-cert -d -r trustRoot -k /Library/Keychains/System.keychain argus-root-ca.crt
Debian or UbuntuCopy the file to /usr/local/share/ca-certificates/ and run sudo update-ca-certificates.
FirefoxFirefox has its own certificate store. Import the file in its settings.

The certificate authority is kept in the argus_caddy-data volume. Keep that volume: a new one means a new root certificate to install on every computer. Without SITE_HOSTS, Caddy issues a certificate for any name it is asked for. On a shared network, set SITE_HOSTS.

Behind another proxy​

site-api trusts the client address in X-Forwarded-For only from Caddy. Caddy has a fixed address on an internal Docker network (PROXY_CADDY_IP, default 172.30.96.2 in PROXY_SUBNET=172.30.96.0/28). If that subnet clashes with a network on the host, change PROXY_SUBNET, PROXY_IP_RANGE and PROXY_CADDY_IP together.

If you put another reverse proxy or load balancer in front of Caddy, set TRUSTED_PROXY_IPS to a comma-separated list of Caddy's address and that proxy's address. Otherwise sign-in throttling and the audit log see the proxy's address instead of the client's.

4. Check the GPU (GPU hosts only)​

Run the GPU check from the requirements:

docker run --rm --gpus all nvidia/cuda:12.4.1-base-ubuntu22.04 nvidia-smi

If it doesn't list your GPU, fix the driver or the NVIDIA Container Toolkit before you go on.

5. Start Argus​

Build the images and start all services:

docker compose up -d --build

The first build takes a while. It downloads the base images and the Python and Node.js packages. The edge node image includes PyTorch and the YOLO detection weights.

Before any other service starts, the one-shot migrate service creates or updates the database schema and exits. When everything has started, check the services:

docker compose ps

All services should be running. migrate has already exited, so it isn't listed. postgres, redis, seaweedfs, ollama and caddy should also show healthy. If nothing starts, check docker compose logs migrate and docker compose logs seaweedfs. The clip storage refuses to start without S3_ACCESS_KEY and S3_SECRET_KEY.

On a GPU host, check that both GPU services can see the GPU:

docker compose exec edge-node python3 -c "import torch; print(torch.cuda.is_available())"
docker compose exec ollama nvidia-smi -L

The first command prints True. The second lists your GPU.

6. Download the AI models​

Argus uses these models. All of them run on your hardware.

ModelUsed forHow it gets onto the site
YOLOv8nDetection and tracking on the edge node.Built into the edge node image.
gemma3:4bAlert clip captions and Copilot answers, in Ollama.You pull it.
nomic-embed-textEmbeddings for searching captions, in Ollama.You pull it.

The caption and Copilot models are local language models served by Ollama. You can choose other Ollama models with VISION_MODEL (captions) and COPILOT_MODEL (Copilot) in .env. Pull any model you set.

Pull the default models:

docker compose exec ollama ollama pull gemma3:4b
docker compose exec ollama ollama pull nomic-embed-text
docker compose exec ollama ollama list

The last command lists both models. Ollama keeps them in the argus_ollama-data volume, so they survive restarts and upgrades.

7. Create the first admin account​

  1. In a browser, open https://<site-node>/, where <site-node> is the host name or IP address of the site node. If you changed HTTPS_PORT, add it to the address.
  2. A new site shows First-Time Setup. Enter your email and a password of at least 12 characters, then click Create Admin Account.
  3. You are signed in as an admin.

The setup page works only while the site has no accounts. After that, the dashboard asks you to sign in, and only an admin can add accounts.

Argus has two roles:

RoleCan do
AdminEverything, including managing cameras, zones, detection profiles, event types, workflows, notification channels, retention settings and accounts, and reading the audit log.
OperatorView cameras, alerts and clips, use the Copilot, and assign, acknowledge, resolve and reopen alerts.

To add accounts, open Settings > Team Access. See Users and roles.

8. Add your first camera​

  1. In the dashboard, open Cameras & Edge Nodes.
  2. Add a camera with a Camera Name and the camera's RTSP address as Source URI.
  3. Click Test Connection. Argus grabs one frame from the camera and shows it.
  4. Under Assigned Edge Node, choose edge-1.
  5. Save the camera.

The edge node checks for camera changes every 10 seconds. To watch it start the camera, run:

docker compose logs -f edge-node

A camera that is not assigned to an edge node is not watched. For camera addresses, ports and firewall rules, see Cameras and network.

Add an edge node on another host​

An edge node on another host runs only the edge-node container. It needs:

  • Network access to the site node's PostgreSQL (5432), Redis (6379) and clip storage (8333). The site node doesn't publish these ports by default, so you publish them on its LAN interface, below.
  • Its live video port (8001) reachable from the site node, so that Caddy can serve the node's live video to browsers under /edge/<node-name>/.
  • The edge node credentials. Don't copy the site's own passwords to edge hosts.

On the site node​

  1. Check that EDGE_DB_PASSWORD and EDGE_REDIS_PASSWORD are set in .env. See Edge node credentials.

  2. In .env, set the site node's LAN address, add docker-compose.lan.yml to COMPOSE_FILE, and list every edge node in CADDY_EDGE_UPSTREAMS as name=host:port, including the built-in one. Use your own addresses instead of 192.168.1.50 and 192.168.1.61:

    .env
    ARGUS_LAN_IP=192.168.1.50
    COMPOSE_FILE=docker-compose.yml:docker-compose.gpu.yml:docker-compose.lan.yml
    CADDY_EDGE_UPSTREAMS=edge-1=edge-node:8001,edge-2=192.168.1.61:8001

    docker-compose.lan.yml is in the release folder. It publishes PostgreSQL, Redis and the clip storage on ARGUS_LAN_IP only.

  3. Apply it with docker compose up -d.

  4. Firewall these ports so that only your edge nodes can reach them. Docker publishes them past ufw and firewalld, so use Docker's DOCKER-USER chain. See Firewall.

  5. Keep the site node and the edge hosts on an isolated network segment or VLAN. Database, Redis and clip traffic between them is not encrypted.

On the edge host​

  1. Install Docker Engine with Docker Compose v2. For a GPU, also install the NVIDIA driver and the NVIDIA Container Toolkit.

  2. Copy the edge-node/ folder from the release to a folder on the host, for example /opt/argus-edge, and go to it.

  3. Create .env from the template in that folder:

    cp remote.env.example .env
    chmod 600 .env
  4. Fill in .env. Give the node a name that no other edge node uses, and copy the edge node credentials and LIVE_STREAM_SECRET from the site node's .env:

    .env
    COMPOSE_PROJECT_NAME=argus-edge
    COMPOSE_FILE=docker-compose.remote.yml
    ARGUS_EDGE_NAME=edge-2
    ARGUS_SITE_HOST=192.168.1.50
    ARGUS_EDGE_LAN_IP=192.168.1.61
    EDGE_DB_PASSWORD=<from the site node>
    EDGE_REDIS_PASSWORD=<from the site node>
    LIVE_STREAM_SECRET=<same as the site node>

    docker-compose.remote.yml comes with the folder. It publishes the node's live video port on ARGUS_EDGE_LAN_IP only, and tells browsers to load the node's live video at /edge/<ARGUS_EDGE_NAME>, so use the same name as in CADDY_EDGE_UPSTREAMS. On a GPU host, remove the # from the deploy: lines at the end of that file.

  5. Start it:

    docker compose up -d --build
    docker compose logs -f edge-node

The new node registers itself with the site on its first check-in. In the dashboard, open Cameras & Edge Nodes: the new node shows as online. Assign cameras to it from each camera's settings.

Traffic between Caddy and the edge node is plain HTTP on your LAN, and every live video request still needs a signed link. If the edge node sits behind its own TLS, write its upstream as edge-2=https://<host>:<port>.

Cameras don't move between nodes on their own. If an edge node goes offline, assign its cameras to another node.

If the edge node can't reach Redis​

Edge nodes hand each detection to a small queue per camera, so a slow or unreachable Redis never slows down detection. A short drop in the connection is absorbed: each message is tried up to 3 times, with a short wait in between.

If Redis stays unreachable, the edge node keeps watching its cameras, but drops the detections it can't deliver and logs how many. It doesn't store them for later, and dropped detections can't raise alerts. When Redis is back, it delivers new detections again by itself and logs that it has recovered. Clip requests resume on their own too.

Cameras & Edge Nodes shows such a node as Redis unreachable, in amber, with the number of dropped detections. A node that stopped checking in shows as Offline. The System Health box at the bottom of the menu names the node.

note

The release also contains docker-compose.cluster-demo.yml. It runs a second edge node, edge-2, on the same GPU host, for trying out camera assignment. It needs no published ports.

Offline sites​

A site without internet access needs everything that the install normally downloads: the container images and the Ollama models. You prepare them on a machine with internet access, then copy them to the site.

On a connected machine​

  1. Install Argus on the connected machine with steps 1 to 6 above, using the same release and the same COMPOSE_PROJECT_NAME.

  2. Save the container images to one file:

    docker save -o argus-images.tar $(docker compose config --images)
  3. Export the Ollama models:

    docker compose cp ollama:/root/.ollama/models ./ollama-models

Copy argus-images.tar and the ollama-models folder to the site node, together with the release.

On the site node​

  1. Copy the release to its folder and create .env as in step 2.

  2. Load the images:

    docker load -i argus-images.tar
  3. Start Argus without building:

    docker compose up -d --no-build
  4. Copy the Ollama models in, restart Ollama and check them:

    docker compose cp ./ollama-models/. ollama:/root/.ollama/models/
    docker compose restart ollama
    docker compose exec ollama ollama list

Then go on with step 7. An offline site can't get a public certificate automatically. Use the site certificate authority or your own certificate.

For an offline edge host, save only the edge node image with docker save -o argus-edge-image.tar argus-edge-node, load it on the edge host, and start it with docker compose up -d --no-build.

Next steps​

Was this page helpful?