Grid — Installation & Operations Guide

System Requirements

Software dependencies (Docker, Python 3, Caddy, Git) are installed automatically by the installer.

Fresh Installation

One-Command Install

SSH into your server as root and run:

curl -fsSL https://raw.githubusercontent.com/SMSLYCLOUD/smsly-hosting/main/install.sh -o /tmp/install.sh
sudo bash /tmp/install.sh

What Happens During Installation

Installation Output

When the installer finishes, it prints a summary like this:

═══════════════════════════════════════════
  Grid Installation Complete!
═══════════════════════════════════════════
  Access URL: http://203.0.113.42
  Admin: admin
  Password: /opt/smsly-hosting/.credentials
═══════════════════════════════════════════

The Access URL is always http://YOUR_SERVER_IP for a fresh install — never HTTPS. See "Accessing the Dashboard" below for why.

Deployment Modes

The installer offers two modes. Choose during the interactive prompts. You can switch from IP mode to SSL mode at any time through the Settings UI.

Accessing the Dashboard

IP Mode (No Domain)

1. Open your browser and go to http://YOUR_SERVER_IP (e.g. http://203.0.113.42)
2. Do not use https:// — there is no valid certificate in IP mode
3. If you accidentally visit https://, you will see a "Your connection is not private" warning. Click Advanced → Proceed to site. This redirects you to HTTP automatically
4. Log in with username admin and the password stored in /opt/smsly-hosting/.credentials

SSL Mode (With Domain)

1. Ensure your domain has an A record pointing to your server IP
2. Open your browser and go to https://your-domain.com
3. Caddy automatically provisions a Let's Encrypt certificate on the first visit (may take 5-10 seconds the first time)
4. Subsequent visits are instant with a valid, browser-trusted certificate

Why HTTP in IP Mode?

Let's Encrypt cannot issue certificates for raw IP addresses. The self-signed fallback certificate exists on port 443 only to redirect HTTPS traffic back to HTTP. Browsers warn on self-signed certificates before following the redirect. For a zero-warning experience, always access via HTTP when no domain is configured.

Domain & SSL Setup

How It Works

The system uses Caddy as its reverse proxy and TLS terminator. Caddy automatically provisions and renews Let's Encrypt certificates. The backend generates the Caddyfile dynamically based on your configuration in the database (PlatformConfig model) and applies it without downtime.

Step 1: DNS Setup

Before configuring SSL, your domain must resolve to your server:

Verify propagation:

dig +short your-domain.com
# Should return your server IP

Step 2: Configure via Dashboard

1. Navigate to Settings → Domain & SSL
2. Enter your domain (e.g. grid.your-domain.com)
3. Toggle SSL Enabled ON
4. Enter the server public IP (usually pre-filled)
5. Click Save & Apply

After saving, the backend:

1. Updates the PlatformConfig model in the database
2. Regenerates the Caddyfile with your domain
3. Reloads Caddy with zero downtime
4. Syncs the domain back to the .env file (for future updates)
5. Updates ALLOWED_HOSTS, CSRF_TRUSTED_ORIGINS, CORS_ALLOWED_ORIGINS, and SITE_URL at runtime

Step 3: Access via HTTPS

Visit https://your-domain.com. The first visit may take 5-10 seconds as Caddy obtains the Let's Encrypt certificate on-demand. Subsequent visits are instant.

What the Backend Updates Automatically

When you save domain config via the dashboard, the backend runtime patches all the following Django settings (no restart needed):

How .env Gets Updated

When the PlatformConfig model is saved (via the UI or API), a Django post_save signal fires (signals.py). This signal attempts to write the new DOMAIN, USE_SSL, SITE_URL, CSRF_TRUSTED_ORIGINS, and CORS_ALLOWED_ORIGINS values back to the .env file on the host.

The backend container runs as user smsly (UID 1000). The installer sets .env permissions to 664 with group ownership by GID 1000, so the container can write to it. If the permissions are wrong (e.g. 600 or 644 owned by root), the signal logs a warning and skips the file update — the domain still works because the database is the source of truth, but a future --update run would not pick up the new domain.

To fix this manually if it occurs:

sudo chown root:1000 /opt/smsly-hosting/.env
sudo chmod 664 /opt/smsly-hosting/.env

Switching from IP Mode to SSL Mode

1. Create an A record for your domain → your server IP
2. Wait for DNS propagation (verify with dig +short your-domain.com)
3. Go to Settings → Domain & SSL
4. Enter your domain, toggle SSL ON, click Save & Apply
5. Access via https://your-domain.com

Removing a Domain (Revert to IP Mode)

1. Go to Settings → Domain & SSL
2. Clear the domain field, toggle SSL OFF
3. Click Save & Apply
4. Access via http://<IP>

Wildcard Subdomains

If you enable Wildcard Subdomains, Caddy provisions a *.your-domain.com certificate via Cloudflare's DNS-01 challenge. This requires:

1. Setting Cloudflare API Token (DNS: Edit zone DNS permission) in Settings → Domain & SSL
2. Your domain must be on Cloudflare DNS
3. The wildcard cert covers all *.your-domain.com subdomains automatically

Common Edge Cases

# 1. Check the ask endpoint (must return 200)
curl -s -w "
HTTP %{http_code}
" \
  "http://localhost:8090/api/v1/services/check-domain/?domain=your-domain.com"

# 2. Check Caddy logs for ACME errors
docker logs smsly-hosting-caddy-1 --tail 50

# 3. Force a Caddy reload to retry cert issuance
docker exec smsly-hosting-caddy-1 caddy reload --config /etc/caddy/Caddyfile

docker compose -f docker-compose.prod.yml logs backend --tail 30

ls -la /opt/smsly-hosting/.env
# If owned by root:root, fix with:
sudo chown root:1000 /opt/smsly-hosting/.env
sudo chmod 664 /opt/smsly-hosting/.env

Updating Grid

From the Terminal

cd /opt/smsly-hosting
sudo bash install.sh --update

cd /opt/smsly-hosting
sudo bash install.sh --update-frontend

cd /opt/smsly-hosting
sudo bash install.sh --update-backend

Rollback on Failure

If an update fails, the installer automatically:

1. Stops new containers
2. Restores the previous .env backup
3. Pops the git stash (rolls back code)

Manual rollback:

cd /opt/smsly-hosting
git log --oneline -n 5           # Find the previous commit
git checkout <commit-hash>       # Roll back
docker compose -f docker-compose.prod.yml up -d --build

From the Dashboard

Admins can trigger updates from Settings → System → Update Software.

Managing Services

View Container Status

cd /opt/smsly-hosting
docker compose -f docker-compose.prod.yml ps

View Logs

# All services
docker compose -f docker-compose.prod.yml logs -f

# Specific service
docker compose -f docker-compose.prod.yml logs -f backend
docker compose -f docker-compose.prod.yml logs -f frontend
docker compose -f docker-compose.prod.yml logs -f caddy

Restart Services

# Restart everything
docker compose -f docker-compose.prod.yml restart

# Restart specific service
docker compose -f docker-compose.prod.yml restart backend
docker compose -f docker-compose.prod.yml restart caddy

Health Check

curl http://localhost:8090/health

Container Map

Architecture note: All external traffic enters through Caddy (ports 80/443). Caddy terminates TLS and proxies to nginx (port 80 internal), which routes to the appropriate backend or frontend service. The stack does not expose backend/frontend ports directly to the internet.

Database Operations

Backup

cd /opt/smsly-hosting
docker compose -f docker-compose.prod.yml exec db \
  pg_dump -U smsly_admin smsly_hosting | gzip > backup_$(date +%Y%m%d).sql.gz

Automated Backups

Add to root crontab (crontab -e):

# Daily at 2 AM
0 2 * * * cd /opt/smsly-hosting && docker compose -f docker-compose.prod.yml exec -T db pg_dump -U smsly_admin smsly_hosting | gzip > backups/daily_$(date +\%Y\%m\%d).sql.gz

Restore from Backup

# Stop write-services
docker compose -f docker-compose.prod.yml stop backend celery celery-beat

# Restore
gunzip -c backup_20260211.sql.gz | \
  docker compose -f docker-compose.prod.yml exec -T db psql -U smsly_admin -d smsly_hosting

# Restart
docker compose -f docker-compose.prod.yml start backend celery celery-beat

Reset Admin Password

docker compose -f docker-compose.prod.yml exec backend python manage.py shell -c \
  "from django.contrib.auth import get_user_model; User = get_user_model(); u = User.objects.get(username='admin'); u.set_password('your_new_password'); u.save(); print('Done.')"

Troubleshooting

Security Hardening

Post-Install Checklist

Firewall Setup (UFW)

ufw default deny incoming
ufw default allow outgoing
ufw allow ssh
ufw allow 80/tcp
ufw allow 443/tcp
ufw enable

Port 8090 (nginx direct access) should not be exposed externally — it is bound to 127.0.0.1 by default. Ports 5432 (PostgreSQL), 6379 (Redis), and other internal ports are only accessible within the Docker network and should not be exposed to the internet.

.env File Permissions

The .env file needs 664 permissions with group ownership by GID 1000 because the backend Docker container runs as user smsly (UID 1000). This allows the domain-config signal to persist domain changes from the UI back to .env without requiring SSH access.

Architecture Summary

Understanding the request flow helps diagnose issues:

Browser → https://your-domain.com
  │
  ▼
Caddy (port 443)
  ├─ Terminates TLS (Let's Encrypt cert)
  ├─ On-demand TLS: asks backend "is this domain allowed?"
  │    → GET /api/v1/services/check-domain/?domain=your-domain.com
  │    → 200 OK = proceed, 404 = reject
  └─ Proxies to → nginx (port 80 internal)
                      │
                      ├─ /api/*      → backend (port 8000)
                      ├─ /ws/*       → backend (WebSocket)
                      ├─ /admin/*    → backend
                      ├─ /static/*   → served directly
                      └─ /*          → frontend (port 3000)

Key insight: Caddy's on-demand TLS "ask" endpoint at /api/v1/services/check-domain/ is the gatekeeper for certificate issuance. If it returns 404, Caddy will not obtain a Let's Encrypt certificate for that domain. The endpoint checks (in order): PlatformConfig primary domain, managed servers, service public domains, verified custom domains, and addon domains.