Configuration
Where Astervis keeps its config and how to change it.
Astervis installs with sensible defaults, so a fresh install is ready to use the moment the wizard finishes. When you do need to change something — a port, a credential, the timezone — it lives in one of three files on the server. This page shows you where they are, how to edit them safely, and how to apply your changes.
Everything runs on the customer's own PBX server. There is no remote config panel
and nothing to log into elsewhere: configuration is plain files you can read with
cat and edit with any text editor, plus a couple of installer commands to apply them.
Where configuration lives
Three files hold everything Astervis needs. The first two are what you'll touch day to day; the third is owned by the installer.
| File | What it holds | When you edit it |
|---|---|---|
/opt/astervis/.env | Runtime environment variables — database and Redis credentials, MySQL/CDR connection, ARI/AMI, ports, API URLs, secrets | Most config changes happen here |
/opt/astervis/docker-compose.yml | Container definitions — images, port bindings, volumes, memory limits | Rarely; for resource tuning or advanced overrides |
/etc/astervis/config.toml | Installer state — the choices you made in the wizard (license, domain, SSL type) | Don't hand-edit; the installer reads this |
Both .env and config.toml are created with mode 0600 (root-only) because
they contain database passwords, the BETTER_AUTH_SECRET, and your license key.
Keep those permissions. Don't paste the contents into a chat, ticket, or public log.
What you can configure
Environment variables
Database and Redis credentials, ports, secrets, ARI/AMI, and API URLs in .env.
MySQL connection
The CDR database, the CDC user grants, and the binlog settings the installer configures.
SSL certificates
Reuse a host cert, get a free *.web.astervis.io subdomain, Let's Encrypt, or self-signed.
Real-time sync
How litcdc backfills and streams your call records into TimescaleDB.
Timezone
The database stores UTC; set how dates display. Default is Asia/Tashkent.
View the current configuration
To see what a running install is using, read the files directly. Because they're
root-only, prefix with sudo:
# Runtime environment variables
sudo cat /opt/astervis/.env
# Installer state (license, domain, SSL choice)
sudo cat /etc/astervis/config.tomlFor a live view of what's actually running — which containers are up and healthy — use the installer's status command instead:
sudo astervis-installer statusThat prints a docker compose ps of /opt/astervis with a service / status /
health table, so you can confirm a change took effect.
Change a setting and apply it
The pattern is always the same: edit the file, then restart the affected services
so they pick up the new values. Containers read .env at startup, so a change
isn't live until you restart.
Edit the value
Open /opt/astervis/.env as root and change the variable you need. For
example, to point the admin UI at a new public URL:
BETTER_AUTH_URL=https://calls.example.com:8443
HOST_URL=https://calls.example.com:8443Restart the services
Restart everything from the install directory, or just the one service that reads the value you changed:
cd /opt/astervis
docker compose down && docker compose up -dOr, equivalently, through the installer (which also keeps the boot autostart unit and license agent in sync):
sudo astervis-installer restartConfirm it worked
Check that the services came back healthy:
sudo astervis-installer statusIf a container is restarting, look at its logs with
docker compose logs --tail=100 <service> from /opt/astervis.
Running astervis-installer upgrade updates the installer binary only — it
does not regenerate docker-compose.yml or your .env. Hand edits to those
files are preserved across an upgrade.
Ports
Astervis exposes exactly one port to the outside world: nginx on 8443, where
the product UI lives. Every other service binds to 127.0.0.1, so it's reachable
only from the server itself and from inside the Docker network. This is deliberate —
nothing but the TLS-terminating reverse proxy should be reachable over the network.
| Service | Container | Host binding | Externally reachable |
|---|---|---|---|
| Nginx (reverse proxy / TLS) | astervis-nginx | 8443 | Yes — this is the product URL |
| Backend API (Elysia) | astervis-app | 127.0.0.1:5555 | No |
| Admin (Next.js) | astervis-nextjs | 127.0.0.1:6464 | No |
| TimescaleDB (pg16 + TimescaleDB + pgvector) | astervis-timescaledb | 127.0.0.1:5432 | No |
| Redis | astervis-redis | 127.0.0.1:6380 | No |
| litcdc (CDC) | astervis-litcdc | 127.0.0.1:18088 | No |
| Queue worker (BullMQ) | astervis-queue | — | No |
| replication | astervis-replication | — | No |
| migrate (runs once) | astervis-migrate | — | No |
The admin UI is at:
https://<your-domain-or-IP>:8443Want to serve the UI on the standard 443? Don't change the container's 8443
binding — instead put your own reverse proxy (or a firewall port-forward) in
front of it, or terminate TLS upstream. The internal port map is tuned to avoid
clashing with the PBX's own services (for example, the host's 8088 is
Asterisk's HTTP server, which is why litcdc publishes on 18088).
A note on the installer agent
Separately from the product containers, the installer runs a small local agent
REST API (astervis-agent) on port 9876, bound to the host. It powers
in-product "check for updates" and license polling, and is authenticated with an
X-API-Key header. It's not part of the day-to-day config surface, but you'll see
it in astervis-installer status and in your process list — that's expected.
Frequently asked
Next steps
Start with the configuration task you actually need:
Last updated on