Terra Installation & Operation 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 two .tar files in the images/ folder contain the pre-packaged application 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:

10. Troubleshooting & Support

View live container diagnostics: