Deploying your Wardyn portal

This guide takes a fresh Linux server to a running Wardyn portal on your own domain. Wardyn is self-hosted: the portal and its database live on your infrastructure, under your brand. It reaches the vendor only for a periodic license check, and no employee data ever leaves your network.

1. Prerequisites

• A server you control: Ubuntu 22.04 LTS or newer, 2 vCPU / 2 GB RAM and 20 GB of disk are comfortable for most teams. Root or a sudo user.
• A domain or subdomain for the portal, e.g. portal.company.com, and access to its DNS.
• Your Wardyn license key from the activation email (it starts with WDN-). The matching security secret is provisioned automatically on first check; nothing to paste by hand.

Machine-bound sign-in needs a Chromium browser (Chrome, Edge, Brave, Opera, Vivaldi and others, list in section 8) with the Wardyn sign-in agent extension, section 8. Roles set to the authenticator-app method sign in from any browser.

2. Domain & subdomain (DNS)

Run each portal on its own subdomain. In your DNS provider (or Cloudflare) add an A record:

Propagation takes a few minutes. Confirm it resolves before continuing; HTTPS depends on it:

Running several portals or brands? Add one A record per subdomain and repeat the install (or add one Nginx server block + certificate per subdomain on the same host).

3. Install: one command recommended

The delivered archive (wardyn.zip) carries its own installer. It checks the server, generates every secret on the spot and writes .env (readable by root only), issues the HTTPS certificate and sets up its renewal, sets up a nightly database backup, then starts the portal, PostgreSQL, Redis and Nginx together. At the end it prints the one-time link to the Setup Wizard.

3.1 Docker, if the server does not have it yet

3.2 Unpack and install

It asks for the portal domain, an e-mail for the certificate and your licence key. The same in one line, without questions:

The client address decides how the IP rules work, so the trust mode is set explicitly and never guessed. It is written to .env and applied again on every run of the installer.

The installer prints the location of .env at the end. Save it in your password manager, apart from database backups: without its AES_KEY the stored credentials cannot be decrypted. Running the installer again in the same folder is safe; it never overwrites the secrets in an existing .env.

4. Install: manual (Ubuntu)

Prefer full control, or already run your own database? Install the stack directly.

4.1 Base packages: Node 20, Redis, Nginx, PM2

4.2 PostgreSQL 16 and the database

4.3 App files, dependencies, migrations

4.4 Run under PM2

Serve the frontend (the web/ folder) as static files and reverse-proxy the API to 127.0.0.1:3000 in Nginx:

server {
    server_name portal.company.com;
    root /opt/wardyn/web;
    index login.html;

    location / { try_files $uri $uri.html $uri/ /login.html; }

    location /api/ {
        proxy_pass http://127.0.0.1:3000;
        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_http_version 1.1;
    }
    listen 80;
}

5. Environment reference (.env)

For the manual install. The one-command installer writes this file for you.

This is what your .env should look like. Copy it, then replace every CHANGE_ME value with your own:

# Wardyn portal .env   (fill every CHANGE_ME value)

# database connection: postgresql://DB_USER:PASSWORD@HOST:5432/DB_NAME
#   your_db_user / your_db_name = the user and database you create in step 4.2
DATABASE_URL=postgresql://your_db_user:CHANGE_ME_DB_PASSWORD@localhost:5432/your_db_name
REDIS_URL=redis://localhost:6379

# secrets: generate once and paste the output:
#   openssl rand -hex 64   -> SESSION_SECRET
#   openssl rand -hex 32   -> AES_KEY and MACHINE_SALT
SESSION_SECRET=CHANGE_ME_64_HEX
AES_KEY=CHANGE_ME_32_HEX
MACHINE_SALT=CHANGE_ME_32_HEX

# one-time code that protects the Setup Wizard: openssl rand -hex 16
SETUP_TOKEN=CHANGE_ME_16_HEX

# how the client address is read (Nginx in front of the app: xff, 1 hop)
TRUST_PROXY_MODE=xff
XFF_TRUST_HOPS=1

# your portal domain (the subdomain you set up in step 2)
RP_ID=portal.company.com
RP_ORIGIN=https://portal.company.com

PORT=3000
NODE_ENV=production

On Docker, set the hosts to the compose services instead of localhost: ...@db:5432/... and redis://redis:6379.

The database user, database name and PM2 process name shown as your_db_user / your_db_name are placeholders. Use any names you like; you are not required to use ours. The only rule: the DB user and DB name must be identical across the CREATE commands, DATABASE_URL and your backups.

What each key means:

The one-time e-mail code used during setup is relayed through the vendor's mail service, so you do not need your own email/SMTP configuration. RESEND_API_KEY / EMAIL_FROM are used only as a fallback if the relay cannot be reached.

6. HTTPS

For the manual install. The one-command installer issues the certificate and renews it on its own.

Let's Encrypt (Certbot):

Cloudflare: enable the proxy (orange cloud) on the A record and set SSL mode to Full (strict) with an Origin certificate on the server.

7. First run: Setup Wizard

Open the link the installer printed at the end: https://portal.company.com/setup/?t=<code>. The code is the one-time SETUP_TOKEN from .env; if you open /setup/ without it, the wizard asks for it. The wizard works only until setup is finished. Under every step it says where to change that choice later.

1. Licence. Already filled if the key was given to the installer, otherwise paste it. The portal validates it and stores it encrypted; your company name, edition and modules come with it.
2. ID format for your people.
3. First administrator: name, e-mail (confirmed with a one-time code sent to it) and their ID. When setup is finished, the last screen says how to sign in.
4. Edition. Shown from your licence: structure and the words used on screen.
5. Roles. Owner is always there. Tick only the role templates you use; nothing else is created.
6. Fields on the employee card. Name is fixed, the rest you pick or add.
7. Sign-in: the default method for your people, normally the code from Wardyn Agent. Other methods, such as an authenticator app, can be allowed here and set per role later.
8. Company: name (as on the licence), portal domain and accent colour.

8. Sign-in agent (Chrome extension)

The agent is a free extension, Wardyn Agent (formerly IT Portal Agent), published in the Chrome Web Store. It turns the employee's own computer into the key: it shows a six-digit sign-in code that changes every 15 seconds, and it opens the systems the person is allowed into without showing them a password. An administrator adds the person once in the portal; after that there is nothing for them to remember.

8.1 On each computer

1. Open Wardyn Agent in the Chrome Web Store and click Add to Chrome.
2. Open your portal and press Sync in the extension. It picks up your portal and licence from the page; nothing is typed by hand.
3. Sign in with your user ID and the code the extension shows. A computer the portal has not seen before, your first one included, waits for IT: the request appears in the portal for an IT administrator to approve once. After that the same code signs you in on that computer.

Which browsers

The agent runs in any browser built on Chromium 116 or newer. If the link does not open, search the Chrome Web Store for Wardyn Agent (until the store shows the new name: IT Portal Agent).

8.2 Office machines: bind to the hardware (optional)

Run agent/provision.bat from the delivery archive once per machine, as administrator. It writes the machine's serial number and name for the extension in Chrome, Edge and Brave, so the binding survives a browser reinstall. It writes nothing else and installs nothing. Laptops and machines without it bind by the extension's own device id; that is normal.

8.3 Install for everyone at once (optional)

With Group Policy, Intune or your own image, add the extension to ExtensionInstallForcelist (id nokhapiedndgmkkfkogjdcieohddlfem, update URL https://clients2.google.com/service/update2/crx). The policy exists for Chrome and for Edge; the browser installs it on every machine and people cannot remove it.

9. Verify the install

Manual install, on the server itself:

• PM2 shows wardyn as online (or docker compose ps shows the services up).
• The domain loads over HTTPS and the sign-in agent icon appears in Chrome.
• The license shows as active in the portal (Settings → License).

10. Backups, updates, license states

Backup the database

One-command install: the installer sets up a nightly dump at 03:30 into the backups/ folder next to the installer; dumps are kept 14 days. Run one now with sudo ./backup.sh. Before every database migration the portal also takes its own dump, and the update stops if that dump fails.

Copy the dumps and .env off the server, to different places: a dump is useless without the AES_KEY from .env, and both are lost together if they stay on the same disk.

Manual install:

Update to a new build

From inside the portal (one-command install). Administration → Service → Updates shows the releases offered to your licence with their notes. Nothing installs by itself: the portal keeps running the version it has until the super admin, or an administrator given the Install updates right, presses Install. The portal checks the vendor signature, backs up the database, installs, restarts and runs a health check; if the check fails it returns to the previous version and data by itself. The last five versions are kept, so you can go back from the same screen. A security release is announced at the top of the portal and in the bell.

This needs the update agent that the installer sets up (a small systemd service, python3 on the server). If the screen says the agent is missing, run the installer again in the same folder.

By hand (one-command install): unpack the new wardyn.zip over the same folder (your .env, certificate and backups are not in the archive and stay) and run the installer again with your domain and the same --trust / --hops / --behind-proxy options as the first time, because the trust mode is applied again on every run.

Manual install: replace the app files (keep your .env), then:

License states

11. Troubleshooting

• HTTPS won't issue: DNS isn't pointing at the server yet. Recheck the A record and ping the domain.
• Login code never appears: the agent isn't synced, or the site is open in a browser without the agent. Open the portal in a browser with Wardyn Agent and press Sync.
• "This computer waits for IT": expected on a computer the portal has not seen before. An IT administrator approves the request in the portal, then the same code signs in.
• The Setup Wizard asks for a setup code: use the link the installer printed, or paste SETUP_TOKEN from .env.
• License stuck read-only: confirm the portal domain matches the license, and that outbound HTTPS to wardyn.maxen.world is allowed. Use "Check now" in Settings → License.
• App won't start: check pm2 logs wardyn (or docker compose logs app); most often a wrong DATABASE_URL or a missing secret in .env.

Questions? Reply to your activation email or write to [email protected].