# Backend and Docker Deployment Guide

DecaTone is designed for self-hosted operation using **Docker Compose** or a native **Node.js 20+** environment.

---

## 1. Quick Start via Docker Compose (Recommended)

Create a `docker-compose.yml` file:

```yaml
version: '3.8'

services:
  decatone:
    image: ghcr.io/tylerhats/decatone:latest
    container_name: decatone-app
    restart: unless-stopped
    ports:
      - "4000:4000"
    environment:
      - PORT=4000
      - NODE_ENV=production
      - JWT_SECRET=your_super_secret_jwt_key_here_change_me
    volumes:
      - decatone-data:/app/backend/data
      - decatone-uploads:/app/backend/uploads
      - decatone-branding:/app/backend/data/branding

volumes:
  decatone-data:
  decatone-uploads:
  decatone-branding:
```

### Standardized Docker Image Tags
DecaTone publishes container images to Docker Hub:
- **`tylerhats/decatone:1.2.2`** (Versioned Release)
- **`tylerhats/decatone:latest`** (Stable Tracking)

### Launching the Service
```bash
docker compose up -d
```
Access the web dashboard at `http://<your-server-ip>:4000` to complete the initial Setup Wizard.

---

## 2. Upgrading DecaTone & Container Immutability

When running inside Docker, DecaTone automatically detects the container environment:
- In-container Git modifications and self-overwrites are safely disabled to preserve container immutability.
- In the **Admin Center &rarr; System Updates** panel, the release channel selector controls which **ESP32-S3 firmware branch** the switchboard offers to physical telephones.
- To update the DecaTone server application, pull the updated container image:
  ```bash
  docker compose pull && docker compose up -d
  ```

---

## 3. 100% Full-Program Backups & Disaster Recovery

DecaTone includes a zero-loss automated backup and restore daemon:

### Archive Contents (`.tar.gz`)
Each backup archive contains:
1. `decatone.db` — Complete SQLite database (all user accounts, extensions, hardware settings, call history, friends, and system policies).
2. `branding/` — Custom brand logo, browser favicon, and top-right navigation icons.
3. `uploads/` — All customized voicemail greetings and recorded voice messages.
4. `backup_metadata.json` — Timestamp, DecaTone release version, and database schema migration level.

### Automated Scheduling & Retention
In **Admin Center &rarr; Backups & Restore**:
- **Schedule**: Enable automated backups (Hourly, Daily, or Weekly) at a specific time (e.g. `02:00` AM).
- **Retention**: Set `backup_retention_count` (e.g. keep last 10 backups). Older archives are automatically pruned.
- **Restoration**: Upload any previously generated `.tar.gz` archive. DecaTone extracts all 4 directories and runs SQLite migrations automatically.

---

## 4. Custom Branding, Favicons & Whitelabeling

Administrators can customize switchboard visual identity in **Admin Center &rarr; Settings & Whitelabeling**:
- **Application Display Name**: Customize name shown across the header, login, and registration screens.
- **Brand Logo**: Upload custom PNG/SVG logo.
- **Browser Favicon**: Upload custom `.ico`/`.png` browser tab icon (dynamically injected into all pages).
- **Top-Right Program Icon**: Custom SVG/PNG icon in the navigation bar.
- **Reset to Defaults**: One-click action to restore factory visual branding.

---

## 5. Reverse Proxy & SSL Setup

For secure WebSockets (`wss://`) and browser microphone permissions for the web softphone, place DecaTone behind an SSL reverse proxy:

### A. Nginx Configuration
```nginx
server {
    listen 80;
    server_name phone.example.com;
    return 301 https://$host$request_uri;
}

server {
    listen 443 ssl http2;
    server_name phone.example.com;

    ssl_certificate /etc/letsencrypt/live/phone.example.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/phone.example.com/privkey.pem;

    location / {
        proxy_pass http://127.0.0.1:4000;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        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 86400s;
        proxy_send_timeout 86400s;
    }
}
```

### B. Caddy Configuration
```caddy
phone.example.com {
    reverse_proxy localhost:4000
}
```

---

## 6. Home Assistant & MQTT Integration

1. In the DecaTone web dashboard, go to **Admin Center &rarr; Settings & MQTT**.
2. Configure your broker connection:
   - **Broker URL**: `mqtt://192.168.1.50:1883`
   - **Username / Password**: Your MQTT credentials
   - **HA Discovery Prefix**: `homeassistant`
   - **Intercom Security PIN**: `411`
3. DecaTone auto-registers every physical phone with binary sensors (hook, ringing, call state), volume/gain sliders, DND toggle switches, and Text-to-Speech intercom announcements.