Environment Variables

Configure Voux using the .env file.

Overview

Voux is configured using environment variables defined in the .env file.

Some options can be changed later from /settings, while others are only read when the server starts.

Admin account

Name	Default	What it does
`ADMIN_USERNAME`	`admin`	Username for the first admin account.
`ADMIN_PASSWORD`	`change-this-password`	Password for the first admin account.

Instance settings

Name	Default	What it does
`PORT`	`8787`	The web server port number.
`PUBLIC_BASE_URL`	based on request	Lets you set a fixed site URL (like `https://counter.yourdomain.com`).
`TRUST_PROXY`	`1`	Controls how Voux detects the real visitor IP when something is in front of it (like a proxy or tunnel). This matters for unique counters and rate limits. Use `1` if Voux is behind something like Nginx, Caddy, Cloudflare Tunnel, or another proxy. Use `false` if Voux is exposed directly to the internet (for example `http://server-ip:8787` with nothing in front). `loopback` is only for special setups where a proxy on the same machine forwards traffic through `localhost`. Most users will only need `1` or `false`.
`PRIVATE_MODE`	`false`	If `true`, only users can create new counters.
`ADMIN_PAGE_SIZE`	`5`	How many counters show on each page in the admin panel.
`USERS_PAGE_SIZE`	`4`	How many users show on each page in the users list.
`SHOW_PUBLIC_GUIDES`	`true`	Controls if public guide cards are shown on the main page.
`DEFAULT_ALLOWED_MODES`	`unique,unlimited`	Comma-separated list of modes to allow (`unique`, `unlimited`) for counters.
`COUNTER_CREATE_LIMIT`	`5`	How many counters a single IP can create before hitting the one-minute cooldown.
`COUNTER_CREATE_WINDOW_MS`	`60000`	Window length (in ms) for the above limit. Leave it alone unless you need a different window.
`INACTIVE_DAYS_THRESHOLD`	`30`	Days with no hits before a counter shows an "Inactive" badge in the dashboard.
`BRAND_NAME`	`Voux`	Default display name (used in titles and hero text).
`HOME_TITLE`	`Voux · Simple Free & Open Source Hit Counter`	The homepage `<title>` tag value.
`UNLIMITED_THROTTLE_SECONDS`	`0`	Seconds to wait before counting the same IP again in "Every visit" mode. `0` disables throttling.

Backups

Name	Default	What it does
`BACKUP_DIR`	`./data/backups`	Folder where `.db` backups are stored.
`AUTO_BACKUP_FREQUENCY`	`off`	How often backups run (`off`, `daily`, or `weekly`).
`AUTO_BACKUP_TIME`	`03:00`	Time of day when automatic backups run (24h format).
`AUTO_BACKUP_WEEKDAY`	`0`	Day of the week for weekly backups (`0` = Sunday).
`AUTO_BACKUP_RETENTION`	`7`	How many backup files to keep before older ones are deleted.
`AUTO_BACKUP_INCLUDE_JSON`	`false`	If `true`, JSON exports are included when creating automatic backups.

Counter creation tracker (advanced)

Name	Default	What it does
`COUNTER_CREATE_TRACKER_IDLE_TTL_MS`	`900000`	How long (in ms) inactive IP entries stay in memory before being removed.
`COUNTER_CREATE_TRACKER_CLEANUP_INTERVAL_MS`	`60000`	How often (in ms) the counter creation tracker runs cleanup.
`COUNTER_CREATE_TRACKER_MAX_ENTRIES`	`20000`	Maximum number of tracked IP entries for counter creation.
`COUNTER_CREATE_TRACKER_EVICT_PERCENT`	`0.1`	Percentage of entries removed when the tracker reaches its limit.

Name	Default	What it does
`LOGIN_LIMITER_IDLE_TTL_MS`	`1800000`	How long (in ms) inactive login attempts stay tracked before being removed.
`LOGIN_LIMITER_CLEANUP_INTERVAL_MS`	`60000`	How often (in ms) the login limiter runs cleanup.
`LOGIN_LIMITER_MAX_ENTRIES`	`20000`	Maximum number of tracked login entries in memory.
`LOGIN_LIMITER_EVICT_PERCENT`	`0.1`	Percentage of login entries removed when the limiter reaches its limit.

Development

Name	Default	What it does
`DEV_MODE`	`development`	Use `development` in `.env` to serve HTML/JS/CSS with `no-store` caching.

Last updated on

Data & Backups

How Voux stores data and how to back it up safely.

Overview

Learn what the Voux API is and when you should use it.

On this page

Instance settings

Counter creation tracker (advanced)

Login rate limiter (advanced)