Configuration

Visage is configured through a combination of environment variables, network settings and a small number of files mounted under /opt/visage.

Networking

This section applies when you're deploying Visage behind a reverse proxy like Nginx, Caddy or Apache. There are a few things to keep in mind when wiring it up.

If your reverse proxy applies its own authentication layer, the following URLs should be left open so your visitors' browsers can reach them:

• /i for the ingestion endpoint
• /vis.js for the tracker script
• /api/** (optional) only if you want to expose the token-protected API endpoints (*) to other systems (otherwise, it's fine to leave these doubly protected)

Additionally, if you'd like to enable geo enrichment (see below), your reverse proxy should be configured to send X-Forwarded-For headers containing your visitors' IP addresses, so Visage can resolve them into countries and cities. You'll also need to set the environment variable VISAGE_TRUST_PROXY to true, see Environment vars.

(*) Note: internally, Visage uses the /internal-api/** namespace for its endpoints, so opening up /api/** does not grant any internal access beyond the token-protected API endpoints described here

Geolocation

Country and city breakdowns are derived using MaxMind's free GeoLite-City GeoIP database.

This feature is fully optional: if you don't configure it, Visage still works but won't derive any country or city data from your visitors.

If you wish to enable geolocation enrichment, you'll have to create a free MaxMind account.

Next, verify your e-mail address, configure a password, and log in to your account. The Database Products and Subscriptions overview should list your access to the GeoLite City database.

Next, generate a license key for Visage.

Your MaxMind Account ID and License key should be provided as environment variables to Visage. See Environment vars for more information.

Visage keeps MaxMind's database up to date automatically, checking for updates once per day. Per MaxMind's EULA, any local copy older than 30 days is automatically discarded.

.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

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.

You can back up the data/ directory with any tool you like, including Brespi which natively supports folder-based backups.

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.