Docker Configuration

Start on Boot

To run the Docker container automatically on system startup, run it with the --restart always option. For a complete list of start options, see Docker start on boot.

docker run \
    --restart always \
    -d --name vision-alert \
    -p 8080:8080 \
    -p 2022:2022 \
    -v vision-alert-data:/user-data \
    -e TOKEN=YOUR_API_TOKEN \
    -e LICENSE_KEY=YOUR_LICENSE_KEY \
    -e ADMIN_EMAIL=YOUR_ADMIN_EMAIL \
    -e ADMIN_PASSWORD=YOUR_ADMIN_PASSWORD \
    -e SITE_URL=http://YOUR_SERVER_IP:8080 \
    platerecognizer/vision-alert

danger

Replace YOUR_LICENSE_KEY with your License Key and YOUR_API_TOKEN with your API Token. Get your token and license key. Use On-premises Licenses. Replace YOUR_ADMIN_EMAIL and YOUR_ADMIN_PASSWORD with the credentials for the first administrator account, and YOUR_SERVER_IP with the address users and cameras use to reach the server.

To change any setting, remove the container with docker rm -f vision-alert and run it again with the new values. Your data is kept in the vision-alert-data volume.

Networking

• You may use a different port if 8080 is already used. For example, to use port 8888 do -p 8888:8080. Update SITE_URL to match.
• Port 2022 is the built-in SFTP server. Cameras upload snapshots to it, so it must be reachable from the camera network. Plain FTP is not available.
• If you expose VisionAlert on a public IP address, put a reverse proxy in front of port 8080 and serve it over HTTPS. Set SITE_URL, ALLOWED_HOSTS, and CSRF_TRUSTED_ORIGINS to match the public URL.
• The container needs outbound access to api.platerecognizer.com on ports 80 and 443 for license activation and periodic validation. See Server Addresses for the IP addresses to whitelist. Offline activation is not available.

Environment Variables

LICENSE_KEY

Your VisionAlert On-premises license key. Get it from the VisionAlert page.

Example:

-e LICENSE_KEY=YOUR_LICENSE_KEY

danger

This is required.

TOKEN

Your Plate Recognizer API token. Get it from the VisionAlert page.

Example:

-e TOKEN=YOUR_API_TOKEN

danger

This is required.

ADMIN_EMAIL

Email address of the first administrator account. The account is created on first start.

Example:

-e ADMIN_EMAIL=YOUR_ADMIN_EMAIL

danger

This is required.

ADMIN_PASSWORD

Password of the first administrator account.

Example:

-e ADMIN_PASSWORD=YOUR_ADMIN_PASSWORD

danger

This is required.

SITE_URL

Public URL of the instance. It is used in dashboard links and webhook payloads, so it must match the address users reach the server on.

Example:

-e SITE_URL=http://YOUR_SERVER_IP:8080

danger

This is required.

SFTP_PASSWORD

Admin password of the built-in SFTP server. If unset, a random password is generated on first start and stored on the /user-data volume. Changing the variable after the first start has no effect.

Example:

-e SFTP_PASSWORD=YOUR_SFTP_PASSWORD

CHECK_INTERVAL

Seconds between anomaly check cycles. Each cycle analyzes the snapshots collected since the previous cycle. Defaults to 3600.

Example:

-e CHECK_INTERVAL=1800

ANOMALY_CHECKERS

Number of inference workers used during a check cycle. Defaults to 2. See Speed Optimization.

Example:

-e ANOMALY_CHECKERS=4

WEB_WORKERS

Number of web server workers for the dashboard and API. Defaults to 2.

Example:

-e WEB_WORKERS=4

ALLOWED_HOSTS

Comma-separated list of host names the web server accepts. Set this when serving VisionAlert under a domain name.

Example:

-e ALLOWED_HOSTS=visionalert.example.com

CSRF_TRUSTED_ORIGINS

Comma-separated origins, including the scheme, that are trusted for form submissions. Set this together with ALLOWED_HOSTS when running behind a reverse proxy.

Example:

-e CSRF_TRUSTED_ORIGINS=https://visionalert.example.com

Speed Optimization

• Snapshot analysis runs in batches every CHECK_INTERVAL seconds. Between cycles the container is close to idle, so a short interval mostly changes how quickly alerts are raised, not the total CPU used.
• By default two inference workers analyze snapshots during a cycle. On hosts with 4 or more cores, set ANOMALY_CHECKERS higher, for example -e ANOMALY_CHECKERS=4, to finish each cycle faster.
• Increase WEB_WORKERS only if the dashboard or API becomes slow under many concurrent users.

Data and Storage

Everything VisionAlert writes is stored under /user-data inside the container. The commands above mount this path to a Docker volume named vision-alert-data. You can mount a host directory instead, for example -v /srv/vision-alert:/user-data, to access the files directly.

The volume contains:

• The database. VisionAlert uses SQLite by default (db.sqlite3). See External PostgreSQL Database to use your own database server instead.
• Camera snapshots under media/camera_snapshot.
• SFTP server state.
• Application logs.

warning

VisionAlert keeps every snapshot it receives. There is currently no automatic cleanup, so size the volume for the retention period you need and monitor free disk space. Plan about 0.3 MB of disk per snapshot.

Back up the volume regularly. Stop the container before copying the volume to get a consistent copy of the SQLite database.

External PostgreSQL Database

Set DB_ENGINE=postgres to store data in an external PostgreSQL server instead of the bundled SQLite database. Snapshots and logs stay on the /user-data volume.

Variable	Default	Description
DB_ENGINE	sqlite	Set to postgres to use PostgreSQL.
POSTGRES_HOST	db	Hostname or IP address of the PostgreSQL server.
POSTGRES_PORT	5432	Port of the PostgreSQL server.
POSTGRES_DB	visionalert	Database name. Create it before starting VisionAlert.
POSTGRES_USER	visionalert	Database user with full access to POSTGRES_DB.
POSTGRES_PASSWORD		Password for POSTGRES_USER.

docker run \
    --restart always \
    -d --name vision-alert \
    -p 8080:8080 \
    -p 2022:2022 \
    -v vision-alert-data:/user-data \
    -e TOKEN=YOUR_API_TOKEN \
    -e LICENSE_KEY=YOUR_LICENSE_KEY \
    -e ADMIN_EMAIL=YOUR_ADMIN_EMAIL \
    -e ADMIN_PASSWORD=YOUR_ADMIN_PASSWORD \
    -e SITE_URL=http://YOUR_SERVER_IP:8080 \
    -e DB_ENGINE=postgres \
    -e POSTGRES_HOST=YOUR_POSTGRES_HOST \
    -e POSTGRES_PORT=5432 \
    -e POSTGRES_DB=visionalert \
    -e POSTGRES_USER=visionalert \
    -e POSTGRES_PASSWORD=YOUR_POSTGRES_PASSWORD \
    platerecognizer/vision-alert

Replace YOUR_POSTGRES_HOST with the address of your PostgreSQL server and YOUR_POSTGRES_PASSWORD with the password of the database user. Choose the database engine before the first start; VisionAlert does not migrate existing data between SQLite and PostgreSQL.

Summary

• Set LICENSE_KEY, TOKEN, ADMIN_EMAIL, ADMIN_PASSWORD, and SITE_URL. These are required to start the container.
• Port 2022 must be reachable from your cameras. It is the built-in SFTP server. Plain FTP is not available.
• Allow outbound access to api.platerecognizer.com on ports 80 and 443 for license validation.
• Raise ANOMALY_CHECKERS on hosts with 4 or more cores to finish each check cycle faster.
• Back up the /user-data volume regularly. It holds the database, snapshots, and logs, and snapshots are never pruned automatically.
• Use DB_ENGINE=postgres to store data in an external PostgreSQL database instead of the bundled SQLite.