websitebox/README.md

# WebsiteBox

A Docker-based, self-hosted WordPress deployment system. Provision a VPS, run the installer, and get a working SSL-secured WordPress portfolio site with a single command. All code is auditable, no telemetry, no external dependencies beyond what you explicitly configure.

## Features

- **One-command deploy**: `docker compose up -d` starts everything
- **Automatic SSL**: Let's Encrypt certificates acquired and renewed automatically
- **Secure by default**: Hardened WordPress config, Wordfence firewall, XML-RPC disabled, rate-limited login
- **Age verification**: Pre-configured Age Gate plugin (optional)
- **Automated backups**: UpdraftPlus with configurable retention
- **VPS-agnostic**: Works on any Ubuntu/Debian VPS provider
- **Transparent**: All persistent data in one visible directory (`websitebox-data/`)
- **Auto-restart**: Survives VPS reboots without intervention

## Requirements

- A VPS with Ubuntu 20.04+ or Debian 11+ (1GB RAM minimum, 2GB recommended)
- A domain name with DNS access
- Basic command-line familiarity

### Recommended VPS Providers

| Provider | Min Cost | Notes |
|----------|----------|-------|
| BuyVM | $3.50/mo | Explicit "legal content" policy, free DDoS protection |
| Vultr | $6/mo | No explicit prohibition, widely used |
| OVHcloud | $5.50/mo | European, no explicit prohibition |

## Quick Start

1. **SSH into your VPS** and run the installer:
   ```bash
   curl -fsSL https://raw.githubusercontent.com/websitebox/websitebox/main/install.sh | bash
   ```

2. **Answer the setup wizard** prompts (domain, admin credentials, etc.)

3. **Point your domain's A record** to your server's IP address

4. **Wait for DNS propagation**, then start:
   ```bash
   cd ~/websitebox
   docker compose up -d
   ```

5. **Visit your site** at `https://yourdomain.com` and log in at `https://yourdomain.com/wp-admin`

## Configuration Reference

All configuration is stored in `.env` (generated by `setup.sh`).

| Variable | Description | Default |
|----------|-------------|---------|
| `DOMAIN` | Your domain name | Required |
| `SITE_TITLE` | WordPress site title | My Portfolio |
| `ADMIN_USER` | WordPress admin username | Required |
| `ADMIN_EMAIL` | Admin email (for SSL & WordPress) | Required |
| `ADMIN_PASSWORD` | Admin password | Required |
| `AGE_GATE_ENABLED` | Enable age verification | true |
| `AGE_GATE_MIN_AGE` | Minimum age (18-21) | 18 |
| `SMTP_HOST` | SMTP server for email | (empty) |
| `SMTP_PORT` | SMTP port | 587 |
| `SMTP_USER` | SMTP username | (empty) |
| `SMTP_PASS` | SMTP password | (empty) |
| `BACKUP_RETENTION_DAYS` | Days to keep local backups | 30 |

Database passwords and WordPress salts are auto-generated by `setup.sh` — do not edit them manually.

## Customization Guide

### Theme

WebsiteBox uses a child theme built on [GeneratePress](https://generatepress.com/). Customize it in the WordPress admin under **Appearance > Customize**, or edit the child theme files directly:

```
websitebox-data/wordpress/wp-content/themes/websitebox/
├── style.css          # Custom styles
├── functions.php      # Theme functions
├── theme.json         # Block theme settings (colors, typography)
├── templates/         # Block templates
└── parts/             # Template parts (header, footer)
```

### Plugins

Pre-installed plugins can be managed normally through the WordPress admin. Additional plugins can be installed via **Plugins > Add New**.

- **Age Gate**: Configure under Settings > Age Gate
- **Wordfence**: Configure under Wordfence > Dashboard
- **UpdraftPlus**: Configure under Settings > UpdraftPlus Backups

## Backup & Restore

### Automatic Backups

UpdraftPlus runs automatic backups stored in `websitebox-data/backups/`.

### Manual Backup

```bash
./scripts/backup.sh
```

This creates a database dump and compressed file backup in `websitebox-data/backups/`.

### Cleanup Old Backups

```bash
./scripts/backup.sh --prune-only
```

### Restore

1. Go to **Settings > UpdraftPlus Backups** in wp-admin
2. Select a backup to restore
3. Follow the UpdraftPlus restore wizard

### Remote Backups

For offsite backups, configure UpdraftPlus to send copies to Amazon S3, Backblaze B2, or other remote storage via the UpdraftPlus settings in wp-admin.

## Updating WebsiteBox

```bash
cd ~/websitebox
./scripts/update.sh
```

This pulls the latest changes, rebuilds containers, and runs any migrations. See [docs/UPDATING.md](docs/UPDATING.md) for details.

## Uninstalling

```bash
cd ~/websitebox
docker compose down
# Remove all data (IRREVERSIBLE):
# rm -rf websitebox-data/
```

## Security Practices

See [docs/SECURITY.md](docs/SECURITY.md) for a full overview. Key points:

- SSL via Let's Encrypt with auto-renewal
- WordPress file editor disabled (`DISALLOW_FILE_EDIT`)
- XML-RPC disabled
- Non-standard database table prefix
- Rate limiting on wp-login.php
- Wordfence firewall and brute-force protection
- MariaDB not exposed to host network
- Auto-generated cryptographic passwords and salts

## Troubleshooting

See [docs/TROUBLESHOOTING.md](docs/TROUBLESHOOTING.md) for common issues. Quick commands:

```bash
# Check container health
./scripts/healthcheck.sh

# View logs
docker compose logs -f nginx
docker compose logs -f wordpress
docker compose logs -f db

# Restart a service
docker compose restart nginx

# Re-run WordPress first-boot setup
docker compose exec wordpress rm /var/www/html/.websitebox-setup-complete /var/www/html/.websitebox-setup-partial
docker compose restart wordpress
```

## Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Submit a pull request with DCO sign-off (`git commit -s`)

## License

GPLv3 — see [LICENSE](LICENSE).