Deployment
Butterhost.ing/Visage
MIT

Deployment

Pre-built images are available on the Docker Hub. You can verify Visage starts correctly via the following command:

docker run --rm -p 3000:3000 butterhosting/visage

A more realistic setup mounts local directories at /opt/visage/data and /opt/visage/maxmind, so the SQLite database and the MaxMind GeoIP database survive container restarts:

services:
  visage:
    image: butterhosting/visage
    ports:
      - "3000:3000"
    volumes:
      - ./.htpasswd:/opt/visage/.htpasswd:ro
      - /host-data/visage:/opt/visage/data
      - /host-data/visage-maxmind:/opt/visage/maxmind
    environment:
      VISAGE_TIMEZONE: "Europe/Amsterdam"
      VISAGE_TRUST_PROXY: "true"
      VISAGE_MAXMIND_ACCOUNT_ID: "<ACCOUNT_ID>"
      VISAGE_MAXMIND_LICENSE_KEY: "XXXXXXXXXXXX"

Environment vars

When starting Visage, the following environment variables can be specified.

VariableOptionsDescription
VISAGE_LOGGINGdebug, info, warn, error (default info)Specifies Visage's logging level
VISAGE_TIMEZONEIANA time zone (default UTC)Specifies the timezone used for interface localization, log timestamps and stats bucketing
VISAGE_TRUST_PROXYtrue, false (default false)Specifies whether the X-Forwarded-For request headers can be trusted to contain visitors' IP addresses
VISAGE_MAXMIND_ACCOUNT_IDoptionalMaxMind account ID; geolocation stays off until both MaxMind credentials are given
VISAGE_MAXMIND_LICENSE_KEYoptionalMaxMind license key

.htpasswd

Visage supports HTTP Basic Authentication out of the box. To enable it, place a passwords file at /opt/visage/.htpasswd using the standard Apache format with bcrypt hashes.

alice:$2b$10$0EhE06AyBn4shMGqCkJzqOIPGsYCJxO2mzbgCbfFQ4te5003PiYOK
bob:$2b$10$LbAfTfDmhD9SbroH.JVrc.uUpfNxVDDtjPDTvwE7UaCNnn3PxrQF2

Each line can be created as follows:

htpasswd -nB alice

Authentication only applies to the internal API. The public tracker endpoints (/vis.js and the /i ingestion endpoint) always stay open, so your visitors' browsers can reach them without credentials.

If no passwords file is present, authentication is disabled. For any deployment exposed to the internet, you should either provide an .htpasswd or place Visage behind a reverse proxy that handles it.

/data/

The /opt/visage/data/ directory stores Visage's internal SQLite database, containing:

  • your websites
  • all analytics data
  • any generated API access tokens

Losing the data/ directory means losing all of your analytics, so it's strongly recommended to mount /opt/visage/data/ as a persistent volume.

/maxmind/

The MaxMind database files are stored inside /opt/visage/maxmind/, and should be mounted as a persistent volume as well, to prevent automatic database downloads on every container restart and (accidentally) exceeding MaxMind's daily download limit for your account.

Backups

Make sure the /data/ directory mentioned above is mounted as a host directory, for example -v /host-data/visage:/opt/visage/data. Backups are then straightforward:

  1. Stop the Visage container
  2. Copy the entire data directory to your backup destination, for example rsync -a /host-data/visage/ /host-backups/visage/
  3. Start the Visage container

Restores are the same steps in reverse:

  1. Stop the Visage container
  2. Replace the entire data directory with the backup, for example rsync -a --delete /host-backups/visage/ /host-data/visage/
  3. Start the Visage container

Two things matter in both directions: Visage must stay offline for as long as the copy runs, and the /data/ directory is always copied or replaced in its entirety. Previous backups must be restored into the same or a newer version of Visage.

The /maxmind/ directory needs no backup; Visage downloads the GeoIP database again when it is missing.

Previous
Configuration