Deployment

How to run NexoSaaS: Docker stack, host reverse proxy, base domain, and TLS.

What you are deploying

Customer NexoPOS sites are not separate Compose services. The agent writes files to HOST_AGENT_HOME_BASE, and nginx includes its vhosts.

1. Docker installation

Prerequisites

• Docker Engine + Docker Compose v2
• Ports free (defaults): 8080 (HTTP), 3307 (MySQL host), 6380 (Redis host)

Steps

# From the repository root
cp deploy/.env.docker.example .env

# Optional: set a stable public URL early (production example)
# APP_URL=https://app.yourdomain.com
# APP_ENV=production
# APP_DEBUG=false

docker compose -f deploy/docker-compose.yml up -d --build

Compose entrypoints typically generate APP_KEY and run migrations when configured. Seed catalog + default admin once:

docker compose -f deploy/docker-compose.yml exec app php artisan db:seed --force

Default seeded accounts (dev only):

Open the control plane: http://localhost:8080 (or your APP_URL).

Readiness:

docker compose -f deploy/docker-compose.yml exec app php artisan platform:launch-check

Important environment variables

Product secrets (Stripe, SMTP, GitHub PAT, S3, domain policy) are Admin → Settings, not runtime env.

Host agent modes

Compose is not a full multi-tenant production isolation story by itself. Use script on a VPS when you need production-grade tenant separation.

2. Host Nginx in front of the stack

Recommended production shape:

Internet
   │
   ▼
Host Nginx / Caddy  (TLS termination, :443)
   │  proxy_pass → 127.0.0.1:8080
   ▼
Compose nginx       (control plane + tenant includes)
   │
   ▼
Compose app (PHP-FPM) + tenant docroots on volume

Example host Nginx (control plane)

Replace hostnames and upstream port with yours.

# /etc/nginx/sites-available/nexosaas-control.conf
server {
    listen 80;
    server_name app.yourdomain.com;
    return 301 https://$host$request_uri;
}

server {
    listen 443 ssl http2;
    server_name app.yourdomain.com;

    # ssl_certificate     /etc/letsencrypt/live/app.yourdomain.com/fullchain.pem;
    # ssl_certificate_key /etc/letsencrypt/live/app.yourdomain.com/privkey.pem;

    client_max_body_size 64M;

    location / {
        proxy_pass http://127.0.0.1:8080;
        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_read_timeout 120s;
    }
}

Set:

APP_URL=https://app.yourdomain.com

Laravel trusts forwarded headers when configured for your proxy setup; ensure the app sees HTTPS correctly so signed URLs and cookies stay secure.

Screenshot placeholder: Browser open on the control plane login at your public HTTPS URL

Tenant hostnames

• Docker / local agent: tenant nginx configs are written under {HOST_AGENT_HOME_BASE}/.platform/nginx-enabled/*.conf and included by the Compose nginx (deploy/docker/nginx/default.conf).
• Local browser: http://{install-subdomain}.localhost:8080 often works without /etc/hosts.
• Production: DNS for *.base_domain (and custom domains) must reach the same edge that can route to the platform nginx (or the VPS nginx managed by the script agent).

If the host reverse proxy only forwards app.yourdomain.com, tenant subdomains need either:

• the same proxy with a wildcard server_name / separate server blocks, or
• direct exposure of the platform nginx / agent-managed vhosts.

Plan DNS and TLS for tenants together with the base domain (next section).

3. Base domain

Installations get a free platform hostname:

{slug}.{base_domain}

Example: base domain saas.example.com → acme-store.saas.example.com.

Configure in Admin

1. Sign in as platform admin (2FA outside local).
2. Open Admin → Settings → Domain.
3. Set:

DNS

PLATFORM_BASE_DOMAIN in .env only seeds the Admin value on empty settings; runtime uses Admin → Domain.

4. SSL / Let’s Encrypt

Control plane (host reverse proxy)

Using Certbot (example):

# After DNS for app.yourdomain.com points at the VPS
sudo certbot --nginx -d app.yourdomain.com
# or: certbot certonly --webroot ... then point ssl_certificate paths

Using Caddy is often simpler (automatic HTTPS); reverse_proxy to 127.0.0.1:8080.

Tenant certificates

On provision and custom-domain verification, the host agent is responsible for TLS for tenant hostnames (Let’s Encrypt style flow on the VPS / agent path).

Operators should:

1. Ensure the VPS can complete HTTP-01 (or the agent’s chosen challenge) for install hostnames.
2. Set max verified domain changes per day reasonably (default 3) so customers do not burn LE rate limits.
3. Keep public IPv4 accurate so DNS instructions customers see are correct.

Note: Local Docker with *.localhost does not need public LE for day-to-day UI testing.

Payment webhooks

Production gateways must reach HTTPS endpoints, e.g.:

• https://app.yourdomain.com/webhooks/stripe
• https://app.yourdomain.com/webhooks/paddle
• https://app.yourdomain.com/webhooks/mollie

Configure signing secrets under Admin → Settings → Billing Settings.

5. Post-deploy checklist

Useful ops commands

# Shell into app
docker compose -f deploy/docker-compose.yml exec app bash

# Logs
docker compose -f deploy/docker-compose.yml logs -f app horizon nginx

# Rebuild frontend assets
docker compose -f deploy/docker-compose.yml run --rm -e DOCKER_FORCE_BUILD_ASSETS=true assets

# Wipe evaluation installs (keeps users/catalog/settings)
docker compose -f deploy/docker-compose.yml exec app \
  php artisan platform:reset-evaluation --force