Production Deployment Guide

3.1 Publish API (Linux VPS)

dotnet publish src\Cognitix.API\Cognitix.API.csproj ^
  -c Release -r linux-x64 --self-contained true ^
  -p:BuyerBuild=true ^
  -o C:\publish\Cognitix.API

3.2 Publish WebApp

dotnet workload install wasm-tools
dotnet publish apps\Cognitix.WebApp\Cognitix.WebApp.csproj ^
  -c Release -p:BuyerBuild=true ^
  -o C:\publish\Cognitix.WebApp

Before or after publish, set WebApp config:

{
  "ApiBaseUrl": "https://yourcompany.com/"
}

Copy API output to the server api/ folder. Copy WebApp wwwroot contents to webapp/.

3.3 Server secrets file

On the server only, create api/appsettings.Production.json (use sample deploy/hetzner/appsettings.Production.server.example.json). Set:

• Database connection string
• JWT key (32+ chars) or env COGNITIX_JWT_KEY
• CORS + Jwt Issuer/Audience + BaseUrl/WebAppUrl (table in section 2)
• Licensing:SkipInDevelopment=false + CognitiveCircle ApiKey / HmacSecret

4.1 SSH into the server

ssh YOUR_SSH_USER@YOUR_SERVER_IP

Create a non-root deploy user with sudo if you do not already have one. The sample systemd unit uses User=deploy — change it if your SSH user is different.

4.2 Create folders

sudo mkdir -p /var/www/cognitix-erp/{api,webapp}
sudo mkdir -p /etc/cognitix-erp
sudo chown -R YOUR_SSH_USER:www-data /var/www/cognitix-erp
sudo chmod -R u+rwX,g+rwX /var/www/cognitix-erp

4.3 Database

CognitixERP supports SQL Server, PostgreSQL, or MySQL — one engine per install. The Hetzner samples assume PostgreSQL on the same VPS. Create the database before first Setup Wizard, or let the wizard create it if the login has permission.

PostgreSQL (on the server):

sudo -u postgres psql <<'SQL'
CREATE USER cognitix WITH PASSWORD 'CHANGE_ME_DB_PASSWORD';
CREATE DATABASE cognitix_erp OWNER cognitix;
GRANT ALL PRIVILEGES ON DATABASE cognitix_erp TO cognitix;
\c cognitix_erp
GRANT ALL ON SCHEMA public TO cognitix;
ALTER DEFAULT PRIVILEGES IN SCHEMA public GRANT ALL ON TABLES TO cognitix;
ALTER DEFAULT PRIVILEGES IN SCHEMA public GRANT ALL ON SEQUENCES TO cognitix;
SQL

Use the same password later in appsettings.Production.json.

Or copy the sample script from your PC:

scp deploy/hetzner/postgresql-init.sql YOUR_SSH_USER@YOUR_SERVER_IP:/tmp/
ssh YOUR_SSH_USER@YOUR_SERVER_IP "sudo -u postgres psql -f /tmp/postgresql-init.sql"

Edit the script first if you changed database or user names.

4.4 Production settings (server only)

From your PC (repo root Source/CognitixERP):

scp deploy/hetzner/appsettings.Production.server.example.json YOUR_SSH_USER@YOUR_SERVER_IP:/tmp/appsettings.Production.json

On the server:

ssh YOUR_SSH_USER@YOUR_SERVER_IP
sudo mv /tmp/appsettings.Production.json /var/www/cognitix-erp/api/appsettings.Production.json
sudo nano /var/www/cognitix-erp/api/appsettings.Production.json

Set at least:

1. ConnectionStrings:DefaultConnection — DB host / user / password
2. Jwt:Key — random secret, 32+ characters
3. Cors:AllowedOrigins — https://yourcompany.com
4. AllowedHosts — e.g. yourcompany.com;localhost;127.0.0.1 (CI health check uses Host: localhost)
5. ApiSettings:BaseUrl — https://yourcompany.com (no trailing /api)
6. AppSettings:WebAppUrl — https://yourcompany.com
7. Licensing:ApiKey and Licensing:HmacSecret — from your license provider

Permissions:

sudo chown YOUR_SSH_USER:www-data /var/www/cognitix-erp/api/appsettings.Production.json
sudo chmod 640 /var/www/cognitix-erp/api/appsettings.Production.json

Optional overrides (systemd reads this file):

sudo tee /etc/cognitix-erp/api.env >/dev/null <<'EOF'
# ConnectionStrings__DefaultConnection=...
# Licensing__ApiKey=...
# Licensing__HmacSecret=...
EOF
sudo chmod 600 /etc/cognitix-erp/api.env

4.5 systemd unit

scp deploy/hetzner/cognitix-api.service YOUR_SSH_USER@YOUR_SERVER_IP:/tmp/
ssh YOUR_SSH_USER@YOUR_SERVER_IP
sudo mv /tmp/cognitix-api.service /etc/systemd/system/cognitix-api.service
sudo systemctl daemon-reload
sudo systemctl enable cognitix-api

Edit User= and paths in the unit if your SSH user or install path differs. The sample starts Cognitix.API --urls http://127.0.0.1:5100 with ASPNETCORE_ENVIRONMENT=Production.

4.6 DNS + nginx + SSL

DNS — point your hostname at the VPS:

nginx

1. Copy deploy/hetzner/nginx-site.conf.example.
2. Replace every hostname inside with yourcompany.com.
3. Ensure these locations exist: /api/, /uploads/, /api/uploads/, /, /chat-hub.

scp deploy/hetzner/nginx-site.conf.example YOUR_SSH_USER@YOUR_SERVER_IP:/tmp/yourcompany.com.conf
ssh YOUR_SSH_USER@YOUR_SERVER_IP
sudo mv /tmp/yourcompany.com.conf /etc/nginx/sites-available/yourcompany.com
sudo ln -sf /etc/nginx/sites-available/yourcompany.com /etc/nginx/sites-enabled/
sudo nginx -t
sudo systemctl reload nginx

TLS

sudo certbot --nginx -d yourcompany.com
sudo nginx -t && sudo systemctl reload nginx

4.7 Passwordless restart for CI

Needed only if GitHub Actions will restart the API after each deploy.

sudo visudo -f /etc/sudoers.d/cognitix-erp-deploy

One line (use your SSH user):

YOUR_SSH_USER ALL=(ALL) NOPASSWD: /bin/systemctl restart cognitix-api

Test:

sudo -n systemctl restart cognitix-api

5.1 What you need

• Your code in a GitHub repo (buyer package root = Source/CognitixERP)
• Workflow file: .github/workflows/deploy.yml (sample: deploy/hetzner/github-workflows/deploy.yml)
• Four GitHub Secrets (no secrets inside the YAML file)
• Licensing DLLs committed: lib/Cognitix.Licensing/*.dll
• GitHub Environment named production

5.2 Create deploy SSH key (on your PC)

bash deploy/hetzner/generate-deploy-key.sh

Creates:

• deploy/hetzner/deploy-keys/cognitix_erp_deploy — private (GitHub Secret only)
• deploy/hetzner/deploy-keys/cognitix_erp_deploy.pub — public (server authorized_keys)

Install the public key on the server:

# Windows PowerShell
type deploy\hetzner\deploy-keys\cognitix_erp_deploy.pub | ssh YOUR_SSH_USER@YOUR_SERVER_IP "mkdir -p ~/.ssh && chmod 700 ~/.ssh && cat >> ~/.ssh/authorized_keys && chmod 600 ~/.ssh/authorized_keys"

# Linux / macOS
cat deploy/hetzner/deploy-keys/cognitix_erp_deploy.pub | ssh YOUR_SSH_USER@YOUR_SERVER_IP "mkdir -p ~/.ssh && chmod 700 ~/.ssh && cat >> ~/.ssh/authorized_keys && chmod 600 ~/.ssh/authorized_keys"

Test:

ssh -i deploy/hetzner/deploy-keys/cognitix_erp_deploy YOUR_SSH_USER@YOUR_SERVER_IP

5.3 GitHub Secrets

GitHub → Settings → Secrets and variables → Actions → New repository secret

Copy private key (PowerShell):

Get-Content .\deploy\hetzner\deploy-keys\cognitix_erp_deploy -Raw | Set-Clipboard

5.4 GitHub Environment

Settings → Environments → New environment → name: production
(The workflow uses environment: production.)

5.5 Commit Licensing DLLs + run deploy

This buyer package builds Licensing from DLLs. Commit them or CI fails with missing Cognitix.Licensing.* / CS0234.

git add -f lib/Cognitix.Licensing/*.dll
git add .github/workflows/deploy.yml
git commit -m "Include Licensing DLLs for CI builds."
git push

Then: GitHub → Actions → Deploy → Run workflow (or push to the branch the workflow watches).

5.6 What CI does / does not do

• Builds API + WebApp and copies files to the server
• Restarts cognitix-api (needs the sudoers rule in section 4.7)
• Does not overwrite appsettings.Production.json (keep secrets on the server)
• Does not delete wwwroot/uploads (logos stay)

6.1 Public URLs (same origin)

6.2 Step 1 — Database and URLs

Schema provisioning applies all 18 module DbContexts and usually takes several minutes — keep the tab open.

6.3 Step 2 — Administrator

Create the first admin account. No default password ships with the product. Step 1 must have created a headquarters branch first.

6.4 Step 3 — License / Trial

Activate your Envato purchase code or start the 14-day trial. Production needs internet plus CognitiveCircle keys in server appsettings.Production.json first (Licensing:ApiKey, Licensing:HmacSecret, SkipInDevelopment=false).

6.5 WebApp ApiBaseUrl

{
  "ApiBaseUrl": "https://yourcompany.com/"
}

Confirm webapp/appsettings.json (or wwwroot/appsettings.json after publish) matches after deploy. Copy the snippet from the wizard if it offers a download.

nginx upload locations

Inside your site config, after location /api/:

location /uploads/ {
    proxy_pass         http://127.0.0.1:5100;
    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;
    proxy_set_header   X-Forwarded-Proto $scheme;
    proxy_set_header   Connection keep-alive;
    expires 7d;
    add_header Cache-Control "public";
}

location /api/uploads/ {
    proxy_pass         http://127.0.0.1:5100/uploads/;
    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;
    proxy_set_header   Connection keep-alive;
    expires 7d;
    add_header Cache-Control "public";
}

sudo nginx -t && sudo systemctl reload nginx

Optional PostgreSQL cleanup if old URLs contain /api/uploads/:

UPDATE branching."CompanySetups"
SET "CompanyLogoUrl" = REPLACE("CompanyLogoUrl", '/api/uploads/', '/uploads/'),
    "CompanyFaviconUrl" = REPLACE("CompanyFaviconUrl", '/api/uploads/', '/uploads/')
WHERE "CompanyLogoUrl" LIKE '%/api/uploads/%'
   OR "CompanyFaviconUrl" LIKE '%/api/uploads/%';