Skip to content

Installation

Architecture

A vConfig installation is six containers and their volumes, managed by Docker Compose:

                    HTTPS :443 (vConfig terminates TLS itself; :80 301-redirects)
  Operators ─────────────► app (web, single gunicorn process)
                    │         │  └── in-process syslog receiver (:514)
                    │         │
                    │         ├── prometheus  ┐ share the app's network namespace,
                    │         └── snmp-exporter ┘ so the product's defaults of
                    │                             127.0.0.1:9090 / :9116 are correct
                    │                             with no configuration at all
                    │
  Web terminal :8443 ► gateway (bastion session gateway: WebSocket + SSH proxy + replay)
                              ai-worker (AIOps analysis and remediation, off the web process)
                              db (MariaDB 11)

  app / gateway ── SSH :22 / Telnet :23 / SNMP :161 / ICMP ──► your devices
  app ── HTTPS :443 ──► vconfig.ai (licence activation and update checks only)
  devices ── syslog :514/UDP ──► app (for log insight)

Everything runs on one host; vconfigctl status shows all six at once. Nothing is installed on your devices — vConfig reaches them over SSH/Telnet/SNMP exactly as an engineer would.

Prometheus and snmp-exporter are reachable only from inside the host and publish no ports. vConfig writes their scrape targets into a shared file_sd volume, so adding or removing a device never means editing collector config by hand.

System requirements & sizing

Minimum Recommended
OS Ubuntu 24.04 LTS (x86_64) Ubuntu 24.04 LTS (x86_64)
CPU 4 vCPU 8 vCPU
RAM 8 GB 16 GB
Disk 500 GB+ 1 TB+, SSD
  • Docker is installed automatically if missing. Six containers come up: app, gateway, AI worker, database, Prometheus and snmp-exporter.
  • Disk is the easiest thing to underestimate. Config history, inventory snapshots, monitoring samples, syslog and NetFlow records all keep growing, and the last three scale with device count and sampling rate. Config archives compress well; logs and flow records are what actually fill the disk. Start at the recommended figures if you plan to enable Log Insight or Traffic Analysis.
  • These are whole-machine figures, not tiered by device count: monitoring and logging cost is driven by collection frequency and retention, not device count alone. A 1,000-device site doing config backup only can be lighter than a 100-device site with full flow analysis.
  • vConfig runs a single application process by design (scheduler consistency); scale up (bigger VM), not out.

Network / firewall matrix

Direction Port Purpose
In (operators → vConfig) TCP 443 (configurable) Web UI / API over TLS
In (operators → vConfig) TCP 80 301 redirect to HTTPS only; skipped if the port is taken
In (operators → vConfig) TCP 8443 (configurable) Web terminal and bastion sessions (browser WebSocket)
In (devices → vConfig) UDP/TCP 514 syslog for log insight. Off by default — switch it on under Settings → Syslog before pointing devices at it; the installer falls back to 1514 if the host's rsyslog already holds 514
In (devices → vConfig) UDP 2055 Flow analysis: NetFlow v5/v9, IPFIX and sFlow on one port. Off by default — enable it under Visualization → Traffic analysis → Collector settings. Turn on sampling at the device (1:1000 is a sane start); an unsampled busy router will bury the collector
In (devices → vConfig) TCP 21 (configurable) Image distribution: the control connection for copy ftp://… when a device pulls firmware. Only needed if you push firmware from Bastion → Image repository; the installer publishes 2121 instead when 21 is taken (note that some older switches ignore a custom FTP port)
In (devices → vConfig) TCP 50100-50140 Image distribution: FTP passive data ports. Deliberately narrow so it is easy to justify on a firewall
In (devices → vConfig) TCP 2222 (configurable) Image distribution: built-in SCP source (22 belongs to the host's sshd)
Out (vConfig → devices) TCP 22, 23 SSH/Telnet: backup, inventory, SLA probes, terminal
Out (vConfig → devices) UDP 161 SNMP discovery and metrics
Out (vConfig → devices) ICMP reachability probes
Out (vConfig → vconfig.ai) TCP 443 licence activation, OTA update checks
Out (vConfig → mail server) TCP 587 (configurable) email alerts; only used once SMTP is configured under Settings → Alerts
Out (vConfig → LDAP server) TCP 389 / 636 LDAP/LDAPS sign-in; only used when LDAP authentication is enabled
Out (vConfig → cloud APIs) TCP 443 multi-cloud resource collection; only used once a cloud account is added

Day to day, only 443, 80 and 8443 need to be reachable from your operators' network. Prometheus (9090) and snmp-exporter (9116) listen inside the host only — they neither need nor should have a firewall hole.

The three image-distribution rows apply only when you push firmware to devices from the UI, and only need to be open towards the device network. Skip them entirely if you don't use the feature — install with VCONFIG_TRANSFER_PORTS=0 and the ports are never published.

Container deployments: the address devices connect back to

Inside the container only its own 172.x address is visible, and no switch in the field can reach that. The installer injects the host address (VCONFIG_ADVERTISE_IP) into the container; both the generated copy command and the FTP passive-mode reply use it. If the host has several addresses and devices can only reach one, install with VCONFIG_ADVERTISE_IP=<that address>, or change it afterwards under Settings → Image repository → "Address devices connect back to" — it takes effect immediately.

One-command install

On a clean server, as root:

curl -fsSL https://vconfig.ai/install.sh | sudo bash

The installer:

  1. Installs Docker (if not present).
  2. Frees ports 80/443 — if nginx/apache or anything else holds them they are stopped, and what was stopped is recorded in /opt/vconfig/ports-freed.txt so you can put it back.
  3. Downloads the latest release image and verifies its SHA-256 against the releases API. Dependency images (MariaDB / Prometheus / snmp-exporter) come from Docker Hub when it is reachable and from a bundle on vconfig.ai when it is not — the second path is the normal one on carrier, IDC and mainland-China networks.
  4. Generates random database credentials into /opt/vconfig/.env (mode 600).
  5. Writes docker-compose.yml and starts six containers: app (web/API/collection), gateway (web terminal and bastion), ai-worker (AI analysis), db (MariaDB), prometheus, snmp-exporter.
  6. Generates a self-signed TLS certificate on first boot.
  7. Prints the URL, the initial admin password and the list of ports to open on your firewall, then installs the vconfigctl helper.

Run vconfigctl status afterwards to confirm all six containers are up. Lost the password? vconfigctl password retrieves it — once you have changed it the file is removed, so getting nothing back there is expected.

Installer options

Variable Default Meaning
VCONFIG_DIR /opt/vconfig Installation directory
VCONFIG_PORT 443 host HTTPS port
VCONFIG_HTTP_PORT 80 HTTP redirect port; leave empty to skip
VCONFIG_GW_PORT 8443 web terminal / bastion session port
VCONFIG_SYSLOG_PORT 514 host port for device syslog (falls back to 1514 if taken)
VCONFIG_NETFLOW_PORTS 1 publish the flow-collection port at all. 0 = no
VCONFIG_NETFLOW_PORT 2055 flow collector port — NetFlow v5/v9, IPFIX and sFlow share this one UDP port (told apart by the packet header)
VCONFIG_TRANSFER_PORTS 1 publish the image-distribution ports (FTP/SCP). 0 = publish none
VCONFIG_FTP_PORT 21 FTP control port for image distribution (falls back to 2121 if taken)
VCONFIG_FTP_PASV_MIN / _MAX 50100 / 50140 FTP passive data port range
VCONFIG_SCP_PORT 2222 built-in SCP source port (falls back to 2223 if taken)
VCONFIG_ADVERTISE_IP host's first address the address devices are told to fetch images from
VCONFIG_SNMP_COMMUNITY public default community written into the snmp-exporter config

Example: curl -fsSL https://vconfig.ai/install.sh | sudo VCONFIG_PORT=443 bash

First login

Open https://<your-server> (port 443 by default; http:// redirects automatically), accept the self-signed certificate warning, sign in as admin with the printed password — you must change it immediately. Then follow the Quick Start.

Your own TLS certificate

Upload a CA-issued certificate under Settings → Certificates; HTTP→HTTPS redirect is built in. If you front vConfig with your own reverse proxy instead, proxy to the HTTPS port and preserve Host headers.

Data locations & backup

Path / volume Contents
vconfig_app_data volume (/app/data) TLS certs, encryption keys, license, config archive, settings
vconfig_db_data volume MariaDB (inventory, users, monitoring history, logs)
/opt/vconfig/.env DB credentials, installed version
/opt/vconfig/backups/ output of vconfigctl backup

vconfigctl backup dumps the database and archives the data volume in one shot; it also runs automatically before every vconfigctl update. The directory keeps only the 5 most recent backups and deletes older ones automatically (VCONFIG_KEEP_BACKUPS=<count> to change that) — which is exactly why you should ship /opt/vconfig/backups off-host on your own schedule. It is everything needed for disaster recovery.

Security hardening checklist

  • Restrict TCP 8443 to operator networks (security group / firewall).
  • Create per-operator accounts with the right role (admin / operator / read-only) and device-group scopes; keep admin for break-glass.
  • Use a dedicated read-enabled automation account on devices; vConfig stores it Fernet-encrypted.
  • Enable strict SSH host-key verification (Settings → Backup) once your ssh_known_hosts is populated.
  • If devices send syslog, allow UDP 514 only from device management subnets.

Upgrade, rollback, uninstall

vconfigctl update --check   # is a new version available?
vconfigctl update           # auto-backup, then upgrade in place (<30 s downtime)
vconfigctl status           # containers + installed version
vconfigctl prune            # manually clear old release tarballs/images and backups

Rollback: set the previous version in /opt/vconfig/.env (VCONFIG_VERSION=) and docker compose up -d; restore the matching DB backup if the newer version migrated the schema. After a successful update, cleanup runs automatically: only the current and previous release tarball and image are kept (the previous one is what rollback needs), and anything older is removed.

Uninstall completely (removes all data!):

cd /opt/vconfig && docker compose down -v && cd / && rm -rf /opt/vconfig

Offline / air-gapped environments

Activation needs HTTPS to vconfig.ai and tolerates 14 days offline. For fully air-gapped networks, Enterprise offline activation and manual image transfer are available — contact [email protected].