Server setup guide

01

Requirements

HTTPS and WSS are strongly recommended for reliable production use. A TURN server is recommended when voice or video calls must work across restrictive NAT environments.

02

What you need before starting

• VPS or server with shell access
• One domain, for example hestiachat.site
• Node.js and npm
• Git
• Firewall access for HTTP/HTTPS and the internal app port
• Optional reverse proxy such as Nginx or Caddy
• Optional Firebase config if Android push is enabled
• Optional TURN server for call relay fallback

03

Get the server code

Replace the repository placeholder with the real Hestia server repository URL when it is published.

git clone https://github.com/RuslanLit/Hestia.git hestia-server
cd hestia-server
npm install

04

Configure environment

Create a .env file in the server directory. Keep it private and never publish tokens or service account files.

PORT=3000
SERVER_NAME=Hestia Self-Hosted

OFFLINE_TTL_MS=604800000
REGISTRATION_ENABLED=true
INVITE_ONLY=false
INVITE_CODES=

ADMIN_TOKEN=<GENERATE_A_LONG_RANDOM_TOKEN>
TURN_SERVERS=[]

# Optional Android push placeholders
FIREBASE_PROJECT_ID=
FIREBASE_CLIENT_EMAIL=
FIREBASE_PRIVATE_KEY=

05

Start the server

npm start

The same Node.js app can serve the landing at /, backend config at /api/config, and WebSocket traffic at /ws. It also needs writable persistence storage for its data files or database.

curl http://127.0.0.1:3000/api/config

06

Reverse proxy, HTTPS, and WSS

For production, put the single Hestia Node.js app behind a reverse proxy with TLS. One domain is enough: static pages, release files, HTTP API, and WebSocket traffic all pass through the same handler.

server {
    listen 443 ssl http2;
    server_name hestiachat.site;

    ssl_certificate /path/to/fullchain.pem;
    ssl_certificate_key /path/to/privkey.pem;

    location / {
        proxy_pass http://127.0.0.1:3000;
        proxy_http_version 1.1;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto https;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
    }
}

07

Optional TURN for calls

Direct WebRTC connections work best when peers can reach each other. Restrictive networks or NAT may require TURN relay fallback. Configure TURN servers through TURN_SERVERS.

TURN_SERVERS=[
  {
    "urls": "turn:turn.your-domain.test:3478",
    "username": "<TURN_USERNAME>",
    "credential": "<TURN_PASSWORD>"
  }
]

08

Connect the client

1. Open the Hestia client.
2. Enter your server URL, for example https://hestiachat.site, if the build asks for it.
3. Use the default server URL if your app build already includes it.
4. Register or log in.
5. Create two test users and send a message between them.

09

Verification checklist

• / serves the landing
• /releases/latest.json is reachable
• /api/config is reachable over HTTPS
• WebSocket connects over /ws
• Registration or login works
• Two users can exchange messages
• Offline delivery works within your configured TTL
• File transfer works within configured limits
• Call signaling works
• Audio and video calls have been tested

10

Security basics

• Use HTTPS and WSS for public deployments.
• Choose a strong ADMIN_TOKEN.
• Restrict registration when running a private community server.
• Keep the server, OS, Node.js, and reverse proxy updated.
• Avoid exposing debug logs or sensitive environment values.
• Back up server data carefully and protect backup access.
• Remember that the server operator may still see metadata.

11

Troubleshooting