Installing a2NSoft on Ubuntu Server

Five things. Get all five ready now — stopping halfway to order a domain name is how installations go wrong.

How to read this guide

Every grey box is something you type into the server and press Enter. The $ at the start is the server prompt — do not type it. Use the Copy button rather than retyping, because a single wrong character will produce an error.

Wherever you see erp.example.com, replace it with your own domain. Wherever you see a password placeholder, replace it with your own. Nothing else should be changed.

Connect

On Windows, open PowerShell. On a Mac, open Terminal. Type this, replacing the address with your server's IP:

$ ssh root@203.0.113.10

The first time you connect it asks whether to trust the server. Type yes and press Enter, then enter the password your provider gave you. You are now typing commands on the server.

Update Ubuntu

This installs the latest security patches. It is the first thing to do on any new server.

$ sudo apt update
$ sudo apt upgrade -y

This takes a few minutes. If it finishes with a message asking you to restart, do it — you will be disconnected for about 30 seconds, then reconnect with the same ssh command as above.

$ sudo reboot

The ERP must not run as the administrator. It gets its own account with no password and no ability to log in — so that if the application is ever compromised, the attacker gains almost nothing.

$ sudo adduser --system --group --home /opt/a2nsoft --shell /usr/sbin/nologin a2nsoft

This creates the user a2nsoft and the folder /opt/a2nsoft, which is where the application will live for the rest of this guide.

Four things: Python (runs the application), PostgreSQL (stores the data), Node.js (builds the screens), and Nginx (serves it to browsers safely).

Python, PostgreSQL, Nginx and tools

Ubuntu 24.04 already includes Python 3.12, which is the version a2NSoft needs, so there is nothing extra to add for it.

$ sudo apt install -y python3.12 python3.12-venv python3-pip \
    postgresql postgresql-contrib \
    nginx git curl ca-certificates ufw

Node.js 22

The version Ubuntu ships is too old to build the a2NSoft screens, which require Node 22.12 or newer. Add the official Node repository first:

$ curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -
$ sudo apt install -y nodejs

Check that everything arrived

$ python3.12 --version
$ node --version
$ psql --version
$ nginx -v

If any command says command not found, that package did not install. Run the install command for it again and read the error.

a2NSoft stores everything in PostgreSQL and will refuse to start without it. There is no fallback — by design, because a silently wrong database is worse than none.

Invent a database password

Generate one now and keep it somewhere safe; you will paste it twice — here, and in step 08.

$ openssl rand -base64 24

Create the user and the database

Replace PASTE_DB_PASSWORD_HERE with what you just generated, keeping the single quotes.

$ sudo -u postgres psql -c "CREATE ROLE a2n_app WITH LOGIN PASSWORD 'PASTE_DB_PASSWORD_HERE';"
$ sudo -u postgres psql -c "CREATE DATABASE a2n_production OWNER a2n_app ENCODING 'UTF8';"

Confirm the login works

$ PGPASSWORD='PASTE_DB_PASSWORD_HERE' psql -h 127.0.0.1 -U a2n_app -d a2n_production -c "select 1;"

A small table containing 1 means the database is ready. password authentication failed means the password does not match — create the role again with the correct one.

Give yourself access to the private repository

Choose one of the two methods. A deploy key is the better choice for a server because it is read-only and tied to this machine alone.

Option A — deploy key (recommended)

$ sudo -u a2nsoft -H ssh-keygen -t ed25519 -f /opt/a2nsoft/.ssh/id_ed25519 -N ""
$ sudo cat /opt/a2nsoft/.ssh/id_ed25519.pub

Copy the line that prints. In GitHub, open the repository → Settings → Deploy keys → Add deploy key, paste it, leave "Allow write access" unticked, and save.

Option B — personal access token

In GitHub → Settings → Developer settings → Personal access tokens, create a token with repo read access. You will paste it as the password when git asks.

Fetch the code

$ sudo -u a2nsoft -H git clone git@github.com:sidmectech/a2NSoft-ERP.git /opt/a2nsoft/app

$ sudo -u a2nsoft -H git clone https://github.com/sidmectech/a2NSoft-ERP.git /opt/a2nsoft/app

The application now lives in /opt/a2nsoft/app. Check it arrived:

$ ls /opt/a2nsoft/app

These go into a private folder belonging to the application, not into the system — so they can never conflict with anything else on the server.

$ sudo -u a2nsoft -H python3.12 -m venv /opt/a2nsoft/venv
$ sudo -u a2nsoft -H /opt/a2nsoft/venv/bin/pip install --upgrade pip
$ sudo -u a2nsoft -H /opt/a2nsoft/venv/bin/pip install -r /opt/a2nsoft/app/requirements.txt

The last command takes two to five minutes and prints a long list. The final line should read Successfully installed ....

The screens users see are written in React and have to be compiled once into plain files. The application then serves those files itself — there is no second web server to manage.

$ cd /opt/a2nsoft/app/frontend
$ sudo -u a2nsoft -H npm ci
$ sudo -u a2nsoft -H npm run build

npm ci downloads the exact package versions the project was tested with; it takes a few minutes. npm run build checks the code and produces the finished files.

Confirm the build produced something

$ ls /opt/a2nsoft/app/frontend/dist

If dist is missing or empty the build failed. Scroll up through the output to the first line containing error — that is the real cause; everything after it is noise.

One file holds the database password and the key that signs user sessions. It lives outside the code folder, is readable only by the service, and is never committed to git.

Generate the secret key

$ openssl rand -base64 48

Copy the result. This key signs every user's session cookie; if it changes, everyone is signed out.

Create the file

$ sudo mkdir -p /etc/a2nsoft
$ sudo nano /etc/a2nsoft/a2nsoft.env

A text editor opens. Paste the block below, then replace the two placeholder lines with your real values.

# a2NSoft production settings
A2N_DEBUG=0
A2N_SECRET_KEY=PASTE_THE_48_CHARACTER_SECRET_HERE

# Database (step 04)
A2N_DB_ENGINE=postgresql
A2N_DB_NAME=a2n_production
A2N_DB_USER=a2n_app
A2N_DB_PASSWORD=PASTE_DB_PASSWORD_HERE
A2N_DB_HOST=127.0.0.1
A2N_DB_PORT=5432
A2N_DB_SSLMODE=prefer

# Connection pool and safety timeouts
A2N_DB_POOL_MIN=2
A2N_DB_POOL_MAX=10
A2N_DB_STATEMENT_TIMEOUT_MS=30000
A2N_DB_LOCK_TIMEOUT_MS=15000
A2N_DB_IDLE_TX_TIMEOUT_MS=30000
A2N_DB_APP_NAME=a2nsoft

# Printing service (step 15). Leave as-is if you skip printing.
A2N_GOTENBERG_URL=http://127.0.0.1:3000
A2N_PRINT_TIMEOUT_SECONDS=45

Save and close: press Ctrl+O, then Enter, then Ctrl+X.

Lock the file down

It contains two passwords, so only the service account may read it.

$ sudo chown root:a2nsoft /etc/a2nsoft/a2nsoft.env
$ sudo chmod 640 /etc/a2nsoft/a2nsoft.env

The database exists but is empty. This builds every table the ERP needs.

$ cd /opt/a2nsoft/app/fastapi_app
$ sudo -u a2nsoft -H --preserve-env bash -c 'set -a; . /etc/a2nsoft/a2nsoft.env; set +a; \
    /opt/a2nsoft/venv/bin/python -m alembic upgrade head'

The middle part of that command loads the settings file so the application knows which database to use. You will see the same pattern again — a2NSoft deliberately does not read the settings file by itself, so that starting it from the wrong place fails loudly instead of quietly opening a different database.

Confirm the tables exist

$ sudo -u postgres psql -d a2n_production -c "\dt" | head -20

You should see a list of tables with names beginning foundation_, erp_, a2n_inventory_ and a2n_crm_.

Choose the password first

Minimum twelve characters; sixteen or more is better. You will type it into the command below, and change it after the first sign-in if you prefer.

$ cd /opt/a2nsoft/app/fastapi_app
$ sudo -u a2nsoft -H bash -c 'set -a; . /etc/a2nsoft/a2nsoft.env; set +a; \
/opt/a2nsoft/venv/bin/python - <<"PY"
import sys; sys.path.insert(0, ".")
from app.db import SessionLocal
from app.models import User
from app.security import hash_password
from app.services.companies import create_company
from app.services.util import now

USERNAME = "admin"                        # change if you want
PASSWORD = "PutYourLongPasswordHere"      # CHANGE THIS
COMPANY  = "Your Company Name LLC"        # CHANGE THIS

db = SessionLocal()
if db.query(User).first() is not None:
    print("A user already exists. Nothing was changed."); raise SystemExit(0)
user = User(username=USERNAME, password=hash_password(PASSWORD),
            first_name="System", last_name="Administrator", is_active=True,
            is_staff=False, is_superuser=False, date_joined=now(),
            can_create_company=True)
db.add(user); db.flush()
create_company(db, user, {"code": "AE01", "legal_name": COMPANY,
                          "business_mode": "both", "city": "Dubai"})
db.commit()
print("Created administrator:", USERNAME)
PY'

If it prints A user already exists, an account was created earlier — sign in with that one instead. The command never overwrites an existing account.

A service starts a2NSoft when the server boots, restarts it if it ever stops, and writes its log where you can read it. Without this, the ERP would stop the moment you closed your terminal window.

Create the service file

$ sudo nano /etc/systemd/system/a2nsoft.service

Paste this exactly as it is — nothing in it needs changing:

[Unit]
Description=a2NSoft ERP
After=network.target postgresql.service
Requires=postgresql.service

[Service]
Type=exec
User=a2nsoft
Group=a2nsoft
WorkingDirectory=/opt/a2nsoft/app/fastapi_app
EnvironmentFile=/etc/a2nsoft/a2nsoft.env
ExecStart=/opt/a2nsoft/venv/bin/python -m uvicorn app.main:app \
    --host 127.0.0.1 --port 8000 --workers 3 \
    --proxy-headers --forwarded-allow-ips=127.0.0.1
Restart=always
RestartSec=5
TimeoutStopSec=30

# Hardening: the service can only write where it must.
NoNewPrivileges=true
PrivateTmp=true
ProtectSystem=strict
ProtectHome=true
ReadWritePaths=/opt/a2nsoft/app/data
ProtectKernelTunables=true
ProtectControlGroups=true
RestrictSUIDSGID=true

[Install]
WantedBy=multi-user.target

Save and close (Ctrl+O, Enter, Ctrl+X).

Start it

$ sudo mkdir -p /opt/a2nsoft/app/data
$ sudo chown a2nsoft:a2nsoft /opt/a2nsoft/app/data
$ sudo systemctl daemon-reload
$ sudo systemctl enable --now a2nsoft
$ sudo systemctl status a2nsoft

Check the application answers

$ curl http://127.0.0.1:8000/api/v1/health

This is the health check. It also queries the database, so a successful reply proves the application and the database connection are working. If it fails, read the log:

$ sudo journalctl -u a2nsoft -n 50 --no-pager

a2NSoft listens only on the server itself. Nginx sits in front of it, accepts visitors from the internet, and passes their requests through. It is also what will hold the HTTPS certificate.

Create the site file

$ sudo nano /etc/nginx/sites-available/a2nsoft

Paste the block below and change erp.example.com to your domain — in both places.

server {
    listen 80;
    listen [::]:80;
    server_name erp.example.com;

    # Invoices and attachments. Raise if you upload larger files.
    client_max_body_size 25m;

    access_log /var/log/nginx/a2nsoft.access.log;
    error_log  /var/log/nginx/a2nsoft.error.log;

    location / {
        proxy_pass http://127.0.0.1:8000;
        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;
        # Tells the app the visitor used HTTPS. Sign-in fails without it.
        proxy_set_header X-Forwarded-Proto $scheme;

        # PDF generation can take a while on large documents.
        proxy_connect_timeout 60s;
        proxy_send_timeout    120s;
        proxy_read_timeout    120s;
    }

    # Compiled screens never change without a new filename, so cache them hard.
    location /assets/ {
        proxy_pass http://127.0.0.1:8000;
        proxy_set_header Host $host;
        expires 1y;
        add_header Cache-Control "public, immutable";
    }
}

Enable it

$ sudo ln -s /etc/nginx/sites-available/a2nsoft /etc/nginx/sites-enabled/
$ sudo rm -f /etc/nginx/sites-enabled/default
$ sudo nginx -t
$ sudo systemctl reload nginx

Only reload once you see successful. If the test fails it names the file and line number — that is where the typo is.

A free certificate from Let's Encrypt, installed and renewed automatically. This is not optional — a2NSoft will not let anyone sign in without it.

Install and run Certbot

$ sudo apt install -y certbot python3-certbot-nginx
$ sudo certbot --nginx -d erp.example.com

It asks three things:

1. Your email address — for expiry warnings.
2. Agreement to the terms — type Y.
3. Whether to share your address with the EFF — N is fine.

Certbot then edits your Nginx file for you: it adds the certificate and redirects all http:// traffic to https://. You do not need to change anything by hand.

Confirm renewal is automatic

Certificates last 90 days. Ubuntu renews them for you; this proves it.

$ sudo certbot renew --dry-run
$ sudo systemctl status certbot.timer

Sign in

Open https://erp.example.com in a browser and sign in with the username and password from step 10. The installation is complete.

The firewall allows only what is needed: your SSH connection and web traffic. Everything else — including the database — becomes unreachable from outside.

$ sudo ufw allow OpenSSH
$ sudo ufw allow 'Nginx Full'
$ sudo ufw --force enable
$ sudo ufw status

a2NSoft produces invoices and reports as PDFs through a separate renderer called Gotenberg, which runs in Docker. Skip this section if you do not need PDF output yet — everything else works without it.

Install Docker

$ sudo apt install -y docker.io docker-compose-v2
$ sudo systemctl enable --now docker

Build and start the renderer

$ cd /opt/a2nsoft/app
$ sudo docker compose -f compose.printing.yml build
$ sudo docker compose -f compose.printing.yml up -d
$ sudo docker compose -f compose.printing.yml ps

Check it responds

$ curl http://127.0.0.1:3000/health

Full detail is in the repository at docs/PRINTING.md.

Do this on day one. A backup you set up next month does not protect you today.

Create the backup script

$ sudo nano /usr/local/bin/a2nsoft-backup.sh

#!/bin/bash
set -euo pipefail
DEST=/var/backups/a2nsoft
STAMP=$(date +%Y%m%d-%H%M%S)
mkdir -p "$DEST"

# Compressed custom-format dump: the fastest to restore selectively.
sudo -u postgres pg_dump -Fc a2n_production > "$DEST/a2n_production-$STAMP.dump"

# Keep the settings file too - without it the dump cannot be opened.
cp /etc/a2nsoft/a2nsoft.env "$DEST/a2nsoft.env-$STAMP"

# Keep 14 days.
find "$DEST" -type f -mtime +14 -delete
echo "Backup written: $DEST/a2n_production-$STAMP.dump"

$ sudo chmod 750 /usr/local/bin/a2nsoft-backup.sh
$ sudo /usr/local/bin/a2nsoft-backup.sh

Run it every night at 2am

$ echo '0 2 * * * root /usr/local/bin/a2nsoft-backup.sh >> /var/log/a2nsoft-backup.log 2>&1' \
    | sudo tee /etc/cron.d/a2nsoft-backup
$ sudo chmod 644 /etc/cron.d/a2nsoft-backup

Restoring

$ sudo systemctl stop a2nsoft
$ sudo -u postgres dropdb a2n_production
$ sudo -u postgres createdb -O a2n_app a2n_production
$ sudo -u postgres pg_restore -d a2n_production /var/backups/a2nsoft/a2n_production-YYYYMMDD-HHMMSS.dump
$ sudo systemctl start a2nsoft

Always back up first. The order below matters: new code, new packages, new screens, new tables, then restart.

$ sudo /usr/local/bin/a2nsoft-backup.sh

$ cd /opt/a2nsoft/app
$ sudo -u a2nsoft -H git pull

$ sudo -u a2nsoft -H /opt/a2nsoft/venv/bin/pip install -r requirements.txt

$ cd /opt/a2nsoft/app/frontend
$ sudo -u a2nsoft -H npm ci
$ sudo -u a2nsoft -H npm run build

$ cd /opt/a2nsoft/app/fastapi_app
$ sudo -u a2nsoft -H bash -c 'set -a; . /etc/a2nsoft/a2nsoft.env; set +a; \
    /opt/a2nsoft/venv/bin/python -m alembic upgrade head'

$ sudo systemctl restart a2nsoft
$ curl http://127.0.0.1:8000/api/v1/health

Users are signed out for two or three seconds during the restart. Any work saved before it is safe; anything half-typed on a screen is not.

The eight you will actually use. Keep this page bookmarked.

The log is always the answer: sudo journalctl -u a2nsoft -n 100 --no-pager. These are the messages you are most likely to find in it.

What this document is, and what it is not. Read it before deploying for a paying customer.

Known gaps, carried here rather than hidden

Recommended before the first customer install

1. Add fastapi_app/scripts/create_admin.py so step 10 becomes one command.
2. Run this guide start to finish on a clean Ubuntu 24.04 server and record what differed.
3. Restore a backup into an empty database and confirm the ERP starts against it.
4. Decide the update window and who is allowed to run step 17.