Deployment

This page covers running AutoTestX as a shared server for a team: a Linux machine behind nginx with HTTPS, running as a systemd service. The repository includes scripts that do all of it on Ubuntu 24.04. They were written for AWS Lightsail but work on any Ubuntu 24.04 server you can SSH into.

What gets installed

                        ┌─ app.<domain>  ──▶ AutoTestX on 127.0.0.1:4100 (systemd: autotestx)
                        │    └─ /api/agent/connect (WebSocket)   ├─ code   /opt/autotestx/app
Browser ──https──▶ nginx│                                        ├─ data   /var/lib/autotestx  (mode 700)
   (TLS, Let's Encrypt) │                                        ├─ config /etc/autotestx.env   (mode 600)
                        │                                        └─ agent  /opt/autotestx/agent/AutoTestX-Agent.exe
                        ├─ <domain>      ──▶ website, static files in /var/www/autotestx-site
                        ├─ docs.<domain> ──▶ this documentation, static files in /var/www/autotestx-docs
                        └─ www.<domain>  ──▶ redirects to <domain>

The app has its own subdomain, so its sign-in cookies are never sent to the website, and the website and docs can be updated without restarting it.

File	Role
`deploy/deploy.ps1`	Run on your Windows machine: tests, bundles, builds the agent, uploads, installs, checks health
`deploy/deploy-site.ps1`	Run on your Windows machine: builds the website and docs (`website/`), uploads and publishes them
`deploy/setup-server.sh`	Runs on the server: packages, user, code, build, nginx, systemd. Safe to re-run.
`deploy/autotestx.env.example`	Template for `/etc/autotestx.env`
`deploy/autotestx.service`	systemd unit (runs as user `autotestx`, restarts on failure)
`deploy/nginx-autotestx.conf`	nginx site: HTTP (Let’s Encrypt challenges, redirect to HTTPS)
`deploy/nginx-autotestx-tls.conf`	nginx site: the HTTPS server blocks for the app, website, docs and www
`deploy/nginx-autotestx-static.conf`	nginx snippet for serving the static website and docs
`deploy/nginx-autotestx-agent.conf`	nginx snippet for the agent WebSocket

Server requirements


OS	Ubuntu 24.04
Memory	4 GB recommended (2 GB works with `ATX_POOL_SIZE=1`, `ATX_MAX_ROW_CONCURRENCY=1`). The script adds 2 GB of swap because `npm ci` and the web build peak high next to Chromium.
Ports	22 (SSH), 80 and 443 open
DNS	A records for `<domain>`, `www`, `app` and `docs` pointing at the server
From your PC	Windows with OpenSSH, Node.js, and an SSH key for the server

First installation

Point DNS for <domain>, www.<domain>, app.<domain> and docs.<domain> at the server’s static IP. HTTPS is set up during the deploy, so DNS must be in place first.
Deploy from the project folder on Windows. Pass your server, key and domain (the script’s defaults are for the original autotestx.com server):
Terminal window
```
powershell -ExecutionPolicy Bypass -File deploy/deploy.ps1 -Server ubuntu@203.0.113.10 -Key $env:USERPROFILE\.ssh\my_key -Domain autotestx.example.com -Full
```
-Full also installs and upgrades system packages (Node.js 22, nginx). Use it on the first install.

The script:
1. runs npm test (skip with -SkipTests),
2. bundles the working copy, excluding node_modules, dist, .data and .claude,
3. builds the Windows agent installer with https://app.<Domain> built in, and signs it if ATX_AGENT_SIGN_SCRIPT is set (skip with -SkipAgent),
4. uploads, then runs setup-server.sh on the server, which also gets a Let’s Encrypt certificate for all four names when it doesn’t have one yet (set CERTBOT_EMAIL on the server command for expiry notices),
5. checks that https://app.<Domain>/ answers 200.
setup-server.sh owns the whole nginx site file and rewrites it on every deploy; certbot only fetches the certificate (certonly --webroot), and renews it automatically (certbot.timer), reloading nginx afterwards.
Publish the website and docs:
Terminal window
```
npm run deploy:site
```
Until then, <domain> and docs.<domain> show a “Coming soon” page.
Review settings in /etc/autotestx.env (see Configuration), e.g. add ANTHROPIC_API_KEY, then:
Terminal window
```
sudo systemctl restart autotestx
```
Claim the administrator account. On the sign-in page choose Forgot password? for local@localhost, then read the link from the journal:
Terminal window
```
sudo journalctl -u autotestx -n 50
```
See First sign-in.

Updating

From the project folder on Windows:

npm run deploy

Command	Does
`npm run deploy`	Tests, then deploy
`npm run deploy:skip-tests`	Deploy without running the tests
`npm run deploy:full`	Also upgrade the server’s system packages

npm run deploy -- -SkipTests does not work from PowerShell, which drops the --. Use the named scripts above, or call deploy.ps1 directly with its switches.

An update replaces the code only. The data directory and /etc/autotestx.env are never touched. Settings added in newer versions are appended to the env file once.

Operating the service

sudo systemctl status autotestx        # is it running?
sudo systemctl restart autotestx       # after changing /etc/autotestx.env
sudo journalctl -u autotestx -f        # follow the log (reset links appear here)
sudo nginx -t && sudo systemctl reload nginx

Before you invite users

HTTPS works, and ATX_PUBLIC_URL is the https:// address (secure cookies, correct reset links)
The administrator account is claimed and renamed
Self-registration policy reviewed. It is open by default; change selfRegistration() in packages/server/src/auth-routes.ts.
ATX_VISIBLE_BROWSER=agent, and the agent download works (Profile → Your computers)
Backups of /var/lib/autotestx scheduled (see Data and backup)
Optional: code-signing for the agent (ATX_AGENT_SIGN_SCRIPT), so SmartScreen does not block it

Without the scripts

On any OS with Node.js 20.11+:

npm ci
npx playwright install --with-deps chromium
npm run build
npm run build:web
ATX_PUBLIC_URL=https://autotestx.example.com ATX_DATA_DIR=/srv/autotestx ATX_VISIBLE_BROWSER=agent npm start

Put a TLS reverse proxy in front of port 4100. It must support WebSocket upgrades on /api/agent/connect for the agent, and server-sent events (no buffering) on /api/runs/*/events for live run results. deploy/nginx-autotestx*.conf are working references.