HTTPS Setup with Caddy (Optional)

Why HTTPS Is Needed

The Hivel UI serves plain HTTP on port 3000. Modern browsers restrict APIs like crypto.randomUUID (used on sign-up/KYC pages) to secure contexts. Direct HTTP access fails with "crypto.randomUUID is not a function". Caddy is a lightweight Docker-based reverse proxy that terminates TLS in front of the UI.

Prerequisites

Before proceeding, confirm:

• ✓ Hivel is running and healthy on port 3000

• ✓ Docker is installed on the host

• ✓ SSH access to the host

• ✓ (Option A only) A domain you control with DNS access

Choose Your Option

Option A: Domain + Let's Encrypt (Recommended) Choose this if you have a domain available. Automatic certificate management, no manual renewal.

Option B: Self-Signed Certificate (Testing Only) Choose this only for testing before a domain is available. Not for production. Browsers show untrusted-certificate warnings.

Option A: Domain + Let's Encrypt

Step 1: Configure DNS

Application/Location: Your DNS provider

Create an A record pointing your subdomain to the host's public/reachable IP:

Record Type	Name	Value
A	hivel.yourcompany.com	<host-ip>

Step 2: Open Firewall Ports

Application/Location: Your firewall/security group

Open:

• Port 80 (required for Let's Encrypt HTTP-01 challenge)

• Port 443 (HTTPS)

Step 3: Configure and Start Caddy

Application/Location: Host (via SSH)

Run:

mkdir -p ~/caddy && cd ~/caddy
cat > Caddyfile <<'EOF'
hivel.yourcompany.com {
    reverse_proxy localhost:3000
}
EOF
docker run -d --name caddy --restart unless-stopped --network host \
  -v $(pwd)/Caddyfile:/etc/caddy/Caddyfile \
  -v caddy_data:/data \
  caddy:2

Step 4: Verify Certificate Issuance

Run:

docker logs -f caddy

Success: Logs show "certificate obtained successfully" Next: Open https://hivel.yourcompany.com in a browser. UI loads with a valid certificate

Option B: Self-Signed Certificate (Testing Only)

Use only for testing. Browsers show untrusted-certificate warnings. Never use in production.

Step 1: Open Firewall Port

Application/Location: Your firewall/security group

Open port 443 only.

Step 2: Configure and Start Caddy

Application/Location: Host (via SSH)

Run:

mkdir -p ~/caddy && cd ~/caddy
cat > Caddyfile <<'EOF'
:443 {
    tls internal
    reverse_proxy localhost:3000
}
EOF
docker run -d --name caddy --restart unless-stopped --network host \
  -v $(pwd)/Caddyfile:/etc/caddy/Caddyfile \
  -v caddy_data:/data \
  caddy:2

Step 3: Access the UI

Open https://<host-ip> in a browser and click through the certificate warning.

Upgrade Option B to Option A (Add Domain Later)

When you obtain a domain, upgrade from self-signed to Let's Encrypt:

Application/Location: Host (via SSH)

Run:

cat > ~/caddy/Caddyfile <<'EOF'
hivel.yourcompany.com {
    reverse_proxy localhost:3000
}
EOF
docker restart caddy

Result: Caddy automatically requests a Let's Encrypt certificate on restart. Update firewall to allow ports 80 and 443.

Managing Caddy

docker logs -f caddy
docker restart caddy
docker stop caddy
docker rm -f caddy   # app stays reachable on :3000 directly

Certificates persist in the caddy_data volume.

Caddy Troubleshooting

Certificate not issued:

Run:

dig +short hivel.yourcompany.com
curl -I http://hivel.yourcompany.com
docker logs caddy --tail 100

Common causes: DNS not propagated, port 80 blocked, wrong IP.

---

Connection Refused on Port 443

Application/Location: Host (via SSH)

Run:

docker ps | grep caddy

Confirm firewall allows inbound 443.

Blank Page or 502 Error

Application/Location: Host (via SSH)

Run:

docker ps | grep insightly-ui
curl -I http://localhost:3000

If the UI container is unhealthy, see Troubleshooting.

Configuration Reference:

Item	Value
Reverse proxy	Caddy 2 (Docker container)
Ports opened	80 (Option A only), 443 (both options)
Certificate	Let's Encrypt (A) / self-signed (B)
Renewal	Automatic
Config	~/caddy/Caddyfile
Data volume	caddy_data

Back to Verification and Access

File Locations Quick Reference