CognitixERP Production Deployment

Production Deployment Guide

Same-origin HTTPS deploy for CognitixERP — publish API + WebApp, put nginx (or IIS) in front, then optionally automate updates with GitHub Actions.

Version 1.0.0 Same-origin · nginx / IIS Optional CI/CD

1. Big picture

Use one website for everything (same-origin):

https://yourcompany.com/           → Blazor WebApp
https://yourcompany.com/api/...    → Cognitix.API
https://yourcompany.com/uploads/   → logos & files
On the serverWhere
API files/var/www/cognitix-erp/api
WebApp files/var/www/cognitix-erp/webapp
API processsystemd cognitix-api on 127.0.0.1:5100
Public HTTPSnginx (or IIS) in front
Buyer package: Licensing ships as DLLs in lib/Cognitix.Licensing/. When you publish, use -p:BuyerBuild=true.

Deep Linux guide in the package: Source/CognitixERP/deploy/hetzner/README.md

Next: URLs →

2. URLs you must set

Replace yourcompany.com with your real domain. Keep all values matching.

PlaceValue
Setup Wizard — Frontend URLhttps://yourcompany.com
Setup Wizard — API URLhttps://yourcompany.com (no /api)
WebApp appsettings.json"ApiBaseUrl": "https://yourcompany.com/"
API Jwt Issuer / Audiencehttps://yourcompany.com
API Cors AllowedOriginshttps://yourcompany.com
API ApiSettings:BaseUrlhttps://yourcompany.com
API AppSettings:WebAppUrlhttps://yourcompany.com
Do not put /api at the end of API URL or ApiBaseUrl. The app already adds api/.... Wrong values break logos and uploads.
← Previous Next: Manual publish →

3. Manual deploy (publish on your PC)

From Source/CognitixERP:

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
Never commit this Production file to Git. CI must not overwrite it.
← Previous Next: Linux + nginx →

4. Linux VPS with nginx (recommended)

Full commands live in deploy/hetzner/README.md. Short version:

  1. Folders 
    sudo mkdir -p /var/www/cognitix-erp/{api,webapp}
sudo chown -R YOUR_SSH_USER:www-data /var/www/cognitix-erp
  2. Database — SQL Server, PostgreSQL, or MySQL. Sample PostgreSQL script: deploy/hetzner/postgresql-init.sql
  3. systemd — copy deploy/hetzner/cognitix-api.service, set User=, then: 
    sudo systemctl daemon-reload
sudo systemctl enable cognitix-api
sudo systemctl start cognitix-api
    API listens on http://127.0.0.1:5100 only.
  4. nginx — copy deploy/hetzner/nginx-site.conf.example, change server_name to your domain. Required locations: /, /api/, /uploads/, /api/uploads/, /chat-hub.
  5. HTTPS 
    sudo certbot --nginx -d yourcompany.com
sudo nginx -t && sudo systemctl reload nginx
Logo blank? Add /uploads/ and /api/uploads/ proxy blocks (they are already in the sample nginx file).
← Previous Next: GitHub Actions →

5. GitHub Actions CI/CD

This matches Source/CognitixERP/deploy/hetzner/README.md Part B. Optional, but best for updates.

5.1 What you need

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

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)
Never commit the private key. Never put it in the CodeCanyon ZIP.

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

Secret nameValue
DEPLOY_HOSTYOUR_SERVER_IP
DEPLOY_USERYOUR_SSH_USER
DEPLOY_PATH/var/www/cognitix-erp
DEPLOY_SSH_KEYFull private key text (-----BEGIN OPENSSH PRIVATE KEY----- …)

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 Allow CI to restart the API (once on server)

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
sudo -n systemctl restart cognitix-api

5.6 Commit Licensing DLLs + run deploy

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 main/master).

Success looks like: publish OK → rsync OK → cognitix-api active → health HTTP 200.

5.7 What CI does / does not do

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

More detail: deploy/hetzner/README.md

← Previous Next: Setup Wizard →

6. Setup Wizard after first deploy

  1. Open https://yourcompany.com/setup
  2. Step 1 — company name, Frontend URL + API URL = site origin, pick SQL Server / PostgreSQL / MySQL, create DB
  3. Step 2 — create admin user (no default password ships)
  4. Step 3 — Envato purchase code or 14-day trial (Production needs internet + CognitiveCircle keys)
  5. Login at https://yourcompany.com/users/login
Wait a few seconds after Step 3 while the API restarts, then check health.
← Previous Next: Go-live checks →

7. Go-live checks

curl -i https://yourcompany.com/api/system/health
curl -i -H "Host: localhost" http://127.0.0.1:5100/api/system/health
  • Site loads over HTTPS
  • Login works with your admin account
  • Company logo loads (needs nginx /uploads/)
  • License status is Trial or Active (not DevelopmentSkipped)

Problems? See Troubleshooting FAQ.

← Previous Next: Windows IIS →

8. Windows IIS (short)

  • Install .NET 10 Hosting Bundle + URL Rewrite
  • One HTTPS site for yourcompany.com
  • Serve WebApp static files; reverse-proxy /api/, /uploads/, /chat-hub to the API (same idea as nginx)
  • Set ASPNETCORE_ENVIRONMENT=Production and COGNITIX_JWT_KEY
  • Use the same URL table from section 2

For most buyers, Linux + nginx + optional GitHub Actions is simpler.

← Previous Next: Contact us →

9. Please Contact us

  1. Sign up at https://cognitivebd.com
  2. Create a Support Ticket.
  3. Within 48hr we will reply.

Or email support@cognitivebd.com with your purchase code, version, and screenshots/logs.

← Previous

CognitixERP v1.0.0 — Installation · User Manual · FAQ
Linux CI/CD source of truth: Source/CognitixERP/deploy/hetzner/README.md