Terra Deployment Package & Guide

1. What you need before starting

Ensure your server host meets the following baseline hardware and software prerequisites:

Installing Docker

- Windows / Mac: Download Docker Desktop from docker.com/products/docker-desktop, run the installer, restart when prompted, and launch Docker Desktop until it displays Engine running.
- Linux: Follow the official guide at docs.docker.com/engine/install for your distribution.

To verify Docker is ready, open PowerShell or terminal and execute:

2. Copy package folder to your server

Place the extracted deployment folder in a permanent directory, for example C:\Terra on Windows or /opt/terra on Linux. All setup commands below are run from inside that directory.

Open a command shell inside the directory:

- Windows: Open C:\Terra in File Explorer, click the address bar, type powershell, and press Enter.
- Linux: Run cd /opt/terra in your terminal console.

3. Load the Terra software images

The .tar files in the images/ folder contain the pre-packaged application, background worker, and database migration container images. Import them into Docker:

Each command finishes with Loaded image: .... This only has to be executed once per server.

4. Generate unique security keys

Terra requires a unique set of database passwords and JWT signing keys. These are generated on your server and are known only to you — Amvelt never sees them.

If Node.js is installed locally, execute:

If Node.js is not installed, run the generator through Docker without installing anything:

5. Start the Terra Container Stack

Launch the containers in detached background mode:

The first startup downloads supporting containers and takes 5–15 minutes depending on your internet connection speed. Subsequent restarts take under 30 seconds.

Check that all container services are running properly:

All core services should display status Up. The database migration worker migrate is expected to display status Exited (0) — it executes once to set up the database schema and then exits safely.

6. Create your first Managing Director account

A fresh installation has zero user accounts, and public self-registration is disabled for security. Create the initial administrator account with this command:

Or via Docker if Node.js is not installed:

You can now open a browser and sign in at http://localhost:3000.

7. Activate your licence key

Terra operates in a limited demo mode until licensed.

1. Sign in as Admin and navigate to Admin → Settings → Licence.
2. Copy the Deployment fingerprint string (e.g. 00C6-87FA-7BA2-639A-4576-DC8B).
3. Email the fingerprint to Amvelt sales/support at the email address on your invoice.
4. Amvelt returns a signed licence string.
5. Open .env.docker in Notepad / text editor and paste the string:
   ABS_TERRA_LICENSE=<the string sent to you>
6. Restart the app service:
   docker compose --env-file .env.docker up -d app

Licensed modules unlock instantly upon restart.

8. Everyday Operations & Data Backups

Stop Terra

Start Terra

Automatic Server Boot Restart

Docker automatically starts Terra on system boot as long as Docker Desktop or Docker Engine service is configured to auto-start with Windows/Linux.

Automated Database & File Backups

Execute this command to export a compressed archive of your entire database and document storage:

Copy terra-backup.tar.gz and .env.docker to offsite backup storage weekly. Together they form a 100% complete restore point.

9. Optional Environment Settings

Edit .env.docker to customize ports or configure corporate SMTP email for notifications:

If staff will use Terra from their own computers

By default Terra expects to be used on the server itself. If people will open it from their own machines, set the address they will type. The simplest way is to let the key generator do it:

Then start Terra again:

You can also just edit SITE_URL and SUPABASE_URL in .env.docker by hand. Either way a restart is enough — no new software is needed from ABS.

Getting this wrong is the most common first-day problem: Terra works on the server and nowhere else, and password-reset emails point people at their own computer instead of the server.

Changed in v1.2.0. On earlier versions these addresses were fixed when the software was built, so correcting them meant asking ABS for a rebuilt package. They are now read when Terra starts. For putting Terra on the open internet with HTTPS rather than an office network, contact ABS.

Bot protection (optional)

Terra can put a Cloudflare Turnstile challenge on the sign-in page.

To leave it off, do nothing. Both settings stay empty and sign-in works normally. This is the right choice if the server has no internet access — Turnstile cannot work without reaching Cloudflare.

To turn it on, create a widget at dash.cloudflare.com → Turnstile, add the address your staff use to its allowed domains, then put both keys in .env.docker and restart.

Set both, or neither. If only one is filled in, Terra blocks sign-in on purpose and tells you which one is missing — a half-configured challenge cannot actually check anything. Admin → Settings → System Status always shows the current state.

10. Troubleshooting & Support

View live container diagnostics: