> ## Documentation Index
> Fetch the complete documentation index at: https://help.propops.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Configuration

> Configure your PropOps environment, set up HTTPS with a reverse proxy, secure your firewall, and complete first-time setup.

After Docker is running, configure your environment variables, set up HTTPS, and complete the initial application setup.

***

## Environment variables

Your configuration lives in `docker-data/config/.env`. Open it in any text editor:

```bash theme={null}
nano docker-data/config/.env
```

### Required variables

At a minimum, review and update these values:

```bash theme={null}
# ─── Application ─────────────────────────────────────────────
APP_URL=https://propops.yourcompany.com  # Your public URL — no trailing slash
APP_ENV=production                       # production | development
APP_DEBUG=false                          # Always false in production

# ─── Database ────────────────────────────────────────────────
# These must match the values in docker-compose.yml
DB_HOST=db
DB_NAME=propops
DB_USER=propops_user
DB_PASS=propops_password

# ─── Licence ─────────────────────────────────────────────────
LICENSE_KEY=your_license_key_here        # Issued by PropOps Technologies Ltd

# ─── Mail (SMTP) ─────────────────────────────────────────────
MAIL_HOST=smtp.mailgun.org
MAIL_PORT=587
MAIL_USERNAME=postmaster@mg.yourcompany.com
MAIL_PASSWORD=your_smtp_password
MAIL_FROM_ADDRESS=noreply@yourcompany.com
MAIL_FROM_NAME="PropOps"
MAIL_ENCRYPTION=tls
```

### Optional variables

These enable additional features. Refer to the `.env.example` file for the full list of available variables:

```bash theme={null}
# ─── Push Notifications ──────────────────────────────────────
WEB_PUSH_ENABLED=true
VAPID_PUBLIC_KEY=                        # Generate with web-push tools
VAPID_PRIVATE_KEY=
VAPID_SUBJECT=mailto:admin@yourcompany.com

# ─── WhatsApp Messaging ──────────────────────────────────────
# No external API credentials required — templates are managed in Admin
```

<Tip>
  After changing `.env`, restart the web container for changes to take effect:

  ```bash theme={null}
  docker compose restart web
  ```
</Tip>

### Auto-generated keys

The following keys are generated automatically on first boot. Do not change them after data has been written:

| Variable             | Purpose                                                                                                                        | Generated  |
| -------------------- | ------------------------------------------------------------------------------------------------------------------------------ | ---------- |
| `PII_ENCRYPTION_KEY` | Encrypts personally identifiable information (database fields) and job files (documents, photos, videos, GDPR reports) at rest | First boot |
| `PII_HMAC_KEY`       | Creates searchable hashes of encrypted fields (enables lookups without decrypting data)                                        | First boot |

***

## HTTPS with a reverse proxy

PropOps must be served over HTTPS in production. The recommended approach is Nginx with Certbot (Let's Encrypt) running directly on the host, proxying requests to the Docker container.

### Install Nginx and Certbot

```bash theme={null}
sudo apt-get update
sudo apt-get install nginx certbot python3-certbot-nginx
```

### Create the Nginx site configuration

```nginx theme={null}
server {
    server_name propops.yourcompany.com;

    location / {
        proxy_pass         http://127.0.0.1:8080;
        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;
        client_max_body_size 50M;
    }
}
```

Save to `/etc/nginx/sites-available/propops` and enable it:

```bash theme={null}
sudo ln -s /etc/nginx/sites-available/propops /etc/nginx/sites-enabled/
sudo nginx -t && sudo systemctl reload nginx
```

### Issue an SSL certificate

```bash theme={null}
sudo certbot --nginx -d propops.yourcompany.com
```

Certbot automatically configures HTTPS, redirects HTTP traffic, and sets up auto-renewal every 90 days.

***

## Firewall

At a minimum, expose only the ports your reverse proxy needs:

```bash theme={null}
sudo ufw allow OpenSSH
sudo ufw allow 'Nginx Full'   # Ports 80 and 443
sudo ufw enable
```

<Warning>
  Do **not** expose port `3306` (MariaDB) or `8081` (phpMyAdmin) to the internet. Access phpMyAdmin through an SSH tunnel if needed:

  ```bash theme={null}
  ssh -L 8081:localhost:8081 user@your-server-ip
  # Then open http://localhost:8081 in your browser
  ```
</Warning>

***

## First-time setup

Once PropOps Web is running and you have logged in with the default admin credentials:

<Steps>
  <Step title="Change the default password">
    Go to your profile and set a strong, unique password immediately.
  </Step>

  <Step title="Configure your organisation">
    Go to **Admin → Settings → General** to set your organisation name, logo, and default VAT rate.
  </Step>

  <Step title="Create your first branch">
    Go to **Admin → Branches** and create a branch. Every job in PropOps Web is assigned to a branch.
  </Step>

  <Step title="Invite users">
    Go to **Admin → Users** to create staff accounts and configure their roles and permissions.
  </Step>

  <Step title="Verify email delivery">
    Go to **Admin → Settings → Email** and send a test email to confirm your SMTP configuration is working.
  </Step>
</Steps>

<Tip>
  PropOps includes a built-in maintenance mode you can enable from **Admin → Settings → Maintenance Mode** or via the API (`POST /api/system/maintenance-mode`). Staff still have access while all other users see a maintenance screen.
</Tip>