Installation¶

Architecture¶

A vConfig installation is two containers managed by Docker Compose, plus a data volume:

                    HTTPS :8443 (TLS terminated by vConfig)
  Operators ──────────────► app (vConfig, gunicorn single-worker)
                              │           │
                              │           ├── app_data volume: certs, keys,
                              │           │   configs archive, license
                              ▼           │
                            db (MariaDB 11, db_data volume)

  app ── SSH :22 / Telnet :23 / SNMP :161 / ICMP ──► your network devices
  app ── HTTPS :443 ──► vconfig.ai   (license activation + update check only)
  devices ── syslog :514/UDP ──► app  (optional, for Log Insight)

Everything runs on one host. There is no agent to install on devices — vConfig speaks SSH/Telnet/SNMP to them like an operator would.

System requirements & sizing¶

Managed devices	CPU	RAM	Disk	Notes
≤ 100 (Free/Pro)	2 vCPU	4 GB	40 GB	fine on a small VM
≤ 1,000 (Business)	4 vCPU	8 GB	100 GB	raise backup concurrency
≤ 10,000 (Scale)	8 vCPU	16 GB	300 GB+	SSD strongly recommended

OS: Ubuntu 22.04/24.04, Debian 12, RHEL 9 — x86_64. Docker is installed automatically if missing.
Disk grows with config history, inventory snapshots, monitoring samples and syslog volume. Config archives compress well; budget generously if you enable Log Insight for busy devices.
vConfig runs a single application process by design (scheduler consistency); scale up (bigger VM), not out.

Network / firewall matrix¶

Direction	Port	Purpose
Inbound (operators → vConfig)	TCP 8443 (configurable)	Web UI / API, TLS
Outbound (vConfig → devices)	TCP 22, 23	SSH/Telnet: backup, inventory, SLA probes, terminal
Outbound (vConfig → devices)	UDP 161	SNMP discovery & metrics
Outbound (vConfig → devices)	ICMP	reachability probes
Inbound (devices → vConfig)	UDP 514 (optional)	syslog for Log Insight
Outbound (vConfig → vconfig.ai)	TCP 443	license activation, OTA update check

One-command install¶

On a clean server, as root:

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

The installer:

Installs Docker (if not present).
Downloads the latest release image and verifies its SHA-256 against the releases API.
Generates random database credentials into /opt/vconfig/.env (mode 600).
Writes docker-compose.yml and starts app + db.
Generates a self-signed TLS certificate on first boot.
Prints the URL and the initial admin password, and installs the vconfigctl helper.

Installer options¶

Variable	Default	Meaning
`VCONFIG_DIR`	`/opt/vconfig`	Installation directory
`VCONFIG_PORT`	`8443`	HTTPS port exposed on the host

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

Open https://<your-server>:8443, 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. 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

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. The previous image is kept locally after every update.

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].