Web portal¶
The web portal is the small website behind the links in Voltius emails. It serves:
/invite/<token>: accepting a team invitation, including creating an account for it/verify-email: confirming an email address/2fa/passkey: using a passkey as a second factor/signin,/signupand/account: managing an account from a browser
The server does not serve these pages. Without a portal of your own, VOLTIUS_APP_URL points at the hosted one, which cannot reach your server, so invitation and verification links do not work.
Run it¶
The portal is published as a multi-arch image (linux/amd64, linux/arm64) at ghcr.io/voltiusapp/voltius-portal. The server repository ships it as compose.portal.yml, next to compose.yml. Turn it on and set both sides in the server's .env:
COMPOSE_FILE=compose.yml:compose.portal.yml
VOLTIUS_API_URL=https://voltius.example.com
VOLTIUS_APP_URL=https://app.voltius.example.com
CORS_ORIGINS=https://app.voltius.example.com,tauri://localhost
Then start everything and check the portal:
docker compose up -d
curl http://127.0.0.1:3000/runtime-config
# → {"apiUrl":"https://voltius.example.com"}
With COMPOSE_FILE in .env, every docker compose command in that directory includes the portal. Without VOLTIUS_API_URL, Compose refuses to start rather than run a portal that talks to the hosted service. On Windows, separate the files with ;, or set COMPOSE_PATH_SEPARATOR.
If your server directory predates compose.portal.yml, copy the file next to your compose.yml.
| Variable | Where | Purpose |
|---|---|---|
VOLTIUS_API_URL |
portal | The server's public URL, as browsers reach it. Read when the portal starts, so one image works for any server. Required. |
PORTAL_PORT |
portal | Host port the portal is published on, bound to 127.0.0.1. Default 3000. |
PORTAL_TAG |
portal | Image tag. Default latest; see Tags. |
VOLTIUS_APP_URL |
server | The portal's public URL. Emails link to it. |
CORS_ORIGINS |
server | Must include the portal's origin, since browsers call the API from the portal's pages. Not needed when both share one domain (below). |
WEBAUTHN_RP_ID |
server | Only for passkeys: see Two-factor authentication. |
NEXT_PUBLIC_API_URL is only for building the portal from source. A running image ignores it when VOLTIUS_API_URL is set.
The portal reads GET /v1/meta from your server and adapts to it: with REGISTRATION_ENABLED=false it hides public sign-up, and on a self-hosted server it shows no plans, prices or billing actions.
Tags¶
| Tag | Meaning |
|---|---|
latest |
The newest build of the portal's main branch. Moves on every change. |
sha-<short> |
One exact build. Pin this in production so a restart never changes what runs. |
<version> |
A tagged portal release, when there is one. |
A newer portal works with an older server: what the server does not support yet, such as creating an account from an invitation, it refuses with a message the portal shows. Upgrade by changing PORTAL_TAG and running docker compose up -d portal; roll back the same way. With latest, docker compose pull portal fetches the newest build first.
One domain for both¶
You can serve the portal and the API from one domain. Send /v1/ and the health checks to the server and everything else to the portal:
map $http_upgrade $connection_upgrade {
default upgrade;
'' close;
}
server {
server_name voltius.example.com;
# listen and TLS settings omitted
# Shared terminals use WebSockets and sync uses a long-lived stream, both under /v1/.
location /v1/ {
proxy_pass http://127.0.0.1:14372;
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection $connection_upgrade;
proxy_set_header Host $host;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_buffering off;
proxy_read_timeout 1h;
}
location ~ ^/health {
proxy_pass http://127.0.0.1:14372;
}
location / {
proxy_pass http://127.0.0.1:3000;
proxy_set_header Host $host;
}
}
With Caddy:
voltius.example.com {
@api path /v1/* /health /health/*
reverse_proxy @api localhost:14372
reverse_proxy localhost:3000
}
Then VOLTIUS_API_URL and VOLTIUS_APP_URL are both https://voltius.example.com, and CORS_ORIGINS can stay empty. The desktop app keeps using the same URL as its custom server.
Invitations with registration closed¶
With REGISTRATION_ENABLED=false, people can still join by email invitation. The invitation link opens the portal, which offers Sign in to accept and Create an account. Creating an account works only for the address the invitation was sent to, only while the invitation is pending and the person who sent it can still invite, and the new account joins the team with the role in the invitation. Nobody else can register.
This needs TEAM_INVITES_ENABLED=true and a working email setup.
Invitees can also create the account in the Voltius app, which works with or without a portal of your own: choose Cloud account, enter your server, open Have an invitation link? and paste the link from the email. The app checks it against that server, fills in the invited address and creates the account in the team. If the server refuses an open sign-up, the app opens that field itself.
Without a portal of your own, invitation emails link to the hosted portal (the default VOLTIUS_APP_URL), which cannot see invitations on your server. Its "Invitation not found" page points invitees to the app, but tell them up front to paste the link there.