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 optionaldocker-compose.lan.yml,docker-compose.onvif-macvlan.ymlanddocker-compose.onvif-host.yml), the configuration template.env.example, theedge-node/,site-node/andcaddy/folders, the database schema and migrations indb/, and helper scripts inscripts/. - 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:
| Setting | What it is |
|---|---|
SESSION_SECRET | Signs dashboard sessions. At least 32 characters, and not a placeholder, or site-api doesn't start. |
LIVE_STREAM_SECRET | Shared by site-api and every edge node. Signs the short-lived links for live video. |
POSTGRES_PASSWORD | Password of the site database. POSTGRES_USER and POSTGRES_DB default to site. |
REDIS_PASSWORD | Password of the Redis event streams. |
S3_ACCESS_KEY and S3_SECRET_KEY | Credentials 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:
| Setting | What the edge nodes can do with it |
|---|---|
EDGE_DB_PASSWORD | Log 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_PASSWORD | Log 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:
- CPU host
- GPU host
COMPOSE_PROJECT_NAME=argus
COMPOSE_FILE=docker-compose.yml
COMPOSE_PROJECT_NAME=argus
COMPOSE_FILE=docker-compose.yml:docker-compose.gpu.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.
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:
| Mode | Set in .env | Certificate |
|---|---|---|
| Site certificate authority (default) | Nothing | Caddy 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 name | SITE_DOMAIN=argus.example.com, and optionally ACME_EMAIL | An 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 certificate | TLS_CERT_FILE=/certs/fullchain.pem and TLS_KEY_FILE=/certs/privkey.pem | PEM 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:
| System | How |
|---|---|
| Windows | certutil -addstore Root argus-root-ca.crt, or double-click the file and place it in Trusted Root Certification Authorities. |
| macOS | sudo security add-trusted-cert -d -r trustRoot -k /Library/Keychains/System.keychain argus-root-ca.crt |
| Debian or Ubuntu | Copy the file to /usr/local/share/ca-certificates/ and run sudo update-ca-certificates. |
| Firefox | Firefox 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.
| Model | Used for | How it gets onto the site |
|---|---|---|
| YOLOv8n | Detection and tracking on the edge node. | Built into the edge node image. |
gemma3:4b | Alert clip captions and Copilot answers, in Ollama. | You pull it. |
nomic-embed-text | Embeddings 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
- In a browser, open
https://<site-node>/, where<site-node>is the host name or IP address of the site node. If you changedHTTPS_PORT, add it to the address. - A new site shows First-Time Setup. Enter your email and a password of at least 12 characters, then click Create Admin Account.
- 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:
| Role | Can do |
|---|---|
| Admin | Everything, including managing cameras, zones, detection profiles, event types, workflows, notification channels, retention settings and accounts, and reading the audit log. |
| Operator | View 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
- In the dashboard, open Cameras & Edge Nodes.
- Add a camera with a Camera Name and the camera's RTSP address as Source URI.
- Click Test Connection. Argus grabs one frame from the camera and shows it.
- Under Assigned Edge Node, choose
edge-1. - 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
-
Check that
EDGE_DB_PASSWORDandEDGE_REDIS_PASSWORDare set in.env. See Edge node credentials. -
In
.env, set the site node's LAN address, adddocker-compose.lan.ymltoCOMPOSE_FILE, and list every edge node inCADDY_EDGE_UPSTREAMSasname=host:port, including the built-in one. Use your own addresses instead of192.168.1.50and192.168.1.61:.envARGUS_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:8001docker-compose.lan.ymlis in the release folder. It publishes PostgreSQL, Redis and the clip storage onARGUS_LAN_IPonly. -
Apply it with
docker compose up -d. -
Firewall these ports so that only your edge nodes can reach them. Docker publishes them past ufw and firewalld, so use Docker's
DOCKER-USERchain. See Firewall. -
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
-
Install Docker Engine with Docker Compose v2. For a GPU, also install the NVIDIA driver and the NVIDIA Container Toolkit.
-
Copy the
edge-node/folder from the release to a folder on the host, for example/opt/argus-edge, and go to it. -
Create
.envfrom the template in that folder:cp remote.env.example .env
chmod 600 .env -
Fill in
.env. Give the node a name that no other edge node uses, and copy the edge node credentials andLIVE_STREAM_SECRETfrom the site node's.env:.envCOMPOSE_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.ymlcomes with the folder. It publishes the node's live video port onARGUS_EDGE_LAN_IPonly, and tells browsers to load the node's live video at/edge/<ARGUS_EDGE_NAME>, so use the same name as inCADDY_EDGE_UPSTREAMS. On a GPU host, remove the#from thedeploy:lines at the end of that file. -
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.
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
-
Install Argus on the connected machine with steps 1 to 6 above, using the same release and the same
COMPOSE_PROJECT_NAME. -
Save the container images to one file:
docker save -o argus-images.tar $(docker compose config --images) -
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
-
Copy the release to its folder and create
.envas in step 2. -
Load the images:
docker load -i argus-images.tar -
Start Argus without building:
docker compose up -d --no-build -
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
- Connect your cameras and open the right ports.
- To find cameras with Scan network, put the edge node on the camera network. See Camera discovery (ONVIF).
- Set up backups before you rely on the site.