alwisp/README.md

# ALWISP – Mesh Network Solutions

> Dockerized LAMP stack website for Alabama's wireless ISP and mesh networking company.

---

## Table of Contents

- [Stack Overview](#stack-overview)
- [Installation – Unraid](#installation--unraid)
- [Environment Variables](#environment-variables)
- [Project Structure](#project-structure)
- [Roadmap & Milestones](#roadmap--milestones)
- [Updating the Site](#updating-the-site)
- [Useful Commands](#useful-commands)

---

## Stack Overview

| Container | Image | Purpose |
|---|---|---|
| `alwisp_web` | PHP 8.2 + Apache | Serves the website |
| `alwisp_db` | MySQL 8.0 | Database (internal only) |
| `alwisp_pma` | phpMyAdmin (optional) | DB admin UI on port 8080 |

Each container is deployed individually through the Unraid Container Builder and connected via the `br0` bridge network, giving both the web container and the database container their own dedicated LAN IP addresses. The web container reaches the database by its fixed LAN IP. Data persists in a named Docker volume (`db_data`) and survives container restarts and rebuilds.

---

## Installation – Unraid

### Prerequisites

- Unraid 6.10 or later
- **Community Applications** plugin installed
- **Docker** enabled (Settings → Docker → Enable Docker: Yes)
- **User Scripts** plugin (recommended, for scheduled tasks)
- `br0` enabled — your Unraid host NIC must be bridged (Settings → Network → Enable Bridging: Yes)
- Decide on **two free LAN IPs** before you start — one for the web container, one for the database. Example: `192.168.1.100` (web) and `192.168.1.101` (db). Reserve these in your router's DHCP settings so they are never auto-assigned.

---

### Step 1 – Clone the repository onto your Unraid cache drive

> **Unraid volume mount requirement:** Docker containers on Unraid **cannot reliably access `/mnt/user/` paths**. `/mnt/user` is a FUSE filesystem that is not available inside the Docker container namespace — the container sees an empty directory, Apache finds no files, and returns a 403 Forbidden. Always clone and mount from the **cache drive path directly** (`/mnt/cache/appdata/`).

Open an Unraid terminal (**Tools → Terminal** or SSH in):

```bash
cd /mnt/cache/appdata
git clone https://github.com/jasonMPM/alwisp.git
cd alwisp
```

---

### Step 2 – Build the Docker image

The web container uses a custom image built from the included `Dockerfile`. Build it once from the terminal — Unraid's Container Builder will reference it by name.

```bash
cd /mnt/cache/appdata/alwisp
docker build -t alwisp_web:latest .
```

> After any code change to the `Dockerfile`, re-run this command and then restart the container from the Docker tab.

---

### Step 3 – Add the Database container (alwisp_db)

1. In the Unraid web UI, go to the **Docker** tab
2. Click **Add Container**
3. Fill in the form:

| Field | Value |
|---|---|
| **Name** | `alwisp_db` |
| **Repository** | `mysql:8.0` |
| **Network Type** | `br0` |
| **Fixed IP** | `192.168.1.101` *(your reserved DB IP)* |
| **Restart Policy** | `Unless Stopped` |

4. Scroll to **Environment Variables** and add:

| Key | Value |
|---|---|
| `MYSQL_ROOT_PASSWORD` | *(strong root password)* |
| `MYSQL_DATABASE` | `alwisp` |
| `MYSQL_USER` | `alwisp_user` |
| `MYSQL_PASSWORD` | *(strong db password)* |

5. Scroll to **Path/Volume Mappings** and add:

| Container Path | Host Path | Access Mode |
|---|---|---|
| `/var/lib/mysql` | `/mnt/cache/appdata/alwisp/db_data` | Read/Write |
| `/docker-entrypoint-initdb.d/init.sql` | `/mnt/cache/appdata/alwisp/docker/mysql/init.sql` | Read Only |

6. Click **Apply** — Unraid pulls the MySQL image and starts the container

---

### Step 4 – Add the Web container (alwisp_web)

1. Click **Add Container** again
2. Enable **Advanced View** (toggle in the top-right of the form) so the Extra Parameters field is visible
3. Fill in the form:

| Field | Value |
|---|---|
| **Name** | `alwisp_web` |
| **Repository** | `alwisp_web:latest` *(the image you built in Step 2)* |
| **Network Type** | `br0` |
| **Fixed IP** | `192.168.1.100` *(your reserved web IP)* |
| **Restart Policy** | `Unless Stopped` |
| **Extra Parameters** | `--pull=never` |

> **Why `--pull=never`?** Unraid's Container Builder always tries to pull the repository name from Docker Hub before starting the container. Since `alwisp_web` is a locally built image that doesn't exist on Docker Hub, the pull fails. `--pull=never` tells Docker to use the locally built image as-is and skip the pull attempt.

4. Add **Environment Variables**:

| Key | Value |
|---|---|
| `DB_HOST` | `192.168.1.101` *(the DB container's br0 IP from Step 3)* |
| `DB_NAME` | `alwisp` |
| `DB_USER` | `alwisp_user` |
| `DB_PASS` | *(same password set in Step 3)* |

4. Add **Path/Volume Mappings**:

| Container Path | Host Path | Access Mode |
|---|---|---|
| `/var/www/html` | `/mnt/cache/appdata/alwisp/www` | Read/Write |
| `/etc/apache2/ssl` | `/mnt/cache/appdata/alwisp/docker/apache/ssl` | Read Only |

> The Apache vhost config (`000-default.conf`) is baked directly into the image via `COPY` in the Dockerfile — no bind mount needed. To change it, edit the file in `docker/apache/` and rebuild the image.

5. Click **Apply**

---

### Step 5 – Verify containers are running

```bash
docker ps --filter name=alwisp
```

Both `alwisp_web` and `alwisp_db` should show status `Up`.

Navigate to the web container's dedicated IP in a browser:

```
http://192.168.1.100   → website (replace with your web IP)
```

Because `br0` gives the container its own LAN IP, **no port mapping is needed** — it behaves like a separate device on your network.

---

### Step 6 – Add phpMyAdmin (optional)

For database administration, add a third container:

1. Click **Add Container**
2. Fill in:

| Field | Value |
|---|---|
| **Name** | `alwisp_pma` |
| **Repository** | `phpmyadmin:latest` |
| **Network Type** | `br0` |
| **Fixed IP** | `192.168.1.102` *(another free LAN IP)* |

3. Add **Environment Variables**:

| Key | Value |
|---|---|
| `PMA_HOST` | `192.168.1.101` *(DB container's br0 IP)* |
| `PMA_USER` | `alwisp_user` |
| `PMA_PASSWORD` | *(your db password)* |

4. Click **Apply**, then browse to `http://192.168.1.102`

---

### Step 7 – Point a domain (optional)

Because the web container has a dedicated LAN IP, reverse proxy setup is straightforward:

**Using Nginx Proxy Manager on Unraid:**

1. Add a **Proxy Host** in Nginx Proxy Manager
2. Forward hostname/IP: `192.168.1.100` (the web container's br0 IP), port `80`
3. Enable SSL via Let's Encrypt
4. Drop your certificate files into `/mnt/cache/appdata/alwisp/docker/apache/ssl/` — they are already mounted into the container

---

### Recommended Unraid Share Settings

| Setting | Value |
|---|---|
| Share path | `/mnt/cache/appdata/alwisp` |
| Use cache | Yes (cache-only or prefer) |
| Exclude from backup | No — include in Appdata backup |

---

## Environment Variables

| Variable | Description |
|---|---|
| `DB_ROOT_PASS` | MySQL root password — make this strong |
| `DB_NAME` | Database name (default: `alwisp`) |
| `DB_USER` | Application DB user (default: `alwisp_user`) |
| `DB_PASS` | Application DB password — make this strong |

---

## Project Structure

```
alwisp/
├── docker-compose.yml          # Container orchestration
├── Dockerfile                  # PHP 8.2 + Apache image
├── .env                        # Secrets — never commit
├── .gitignore
├── docker/
│   ├── apache/
│   │   ├── 000-default.conf    # Apache vhost config
│   │   └── ssl/                # TLS certs (gitignored)
│   ├── mysql/
│   │   └── init.sql            # Schema bootstrap on first run
│   └── php/
│       └── php.ini             # PHP runtime settings
└── www/                        # Web root (live-mounted into container)
    ├── index.php               # Front controller / router
    ├── .htaccess               # URL rewriting
    ├── css/style.css           # Design system
    ├── js/main.js              # Nav, counters, scroll reveal
    ├── assets/                 # Logos, images
    ├── includes/
    │   ├── header.php          # Global nav
    │   └── footer.php          # Global footer
    └── pages/
        ├── home.php
        ├── services.php
        ├── coverage.php
        ├── about.php
        ├── contact.php
        └── 404.php
```

---

## Roadmap & Milestones

### Milestone 1 — Foundation `complete`
- [x] Dockerized LAMP stack (PHP 8.2, Apache, MySQL 8.0)
- [x] Front-controller PHP router
- [x] Responsive site skeleton with brand design system
- [x] Homepage: hero, stats bar, services preview, why section, coverage CTA
- [x] Contact form with server-side validation
- [x] Stub pages for all top-level routes (services, coverage, about, contact, 404)
- [x] Security headers, OPcache, and Apache hardening
- [x] Unraid-ready deployment via Docker Compose

---

### Milestone 2 — Content & Plans
- [ ] Populate residential plan tiers (speed tiers, pricing cards)
- [ ] Populate business plan tiers
- [ ] Infrastructure and managed services detail pages
- [ ] About page — company story, team bios, mission statement
- [ ] Real contact info (phone, email, address) wired into header and footer
- [ ] Logo assets added to `/www/assets/` and displayed in nav

---

### Milestone 3 — Coverage Map
- [ ] Embed interactive map (Leaflet.js + OpenStreetMap)
- [ ] Define and store coverage zone polygons in the database
- [ ] Address lookup / service availability check on the homepage CTA
- [ ] Mobile-optimized map view

---

### Milestone 4 — Customer Portal (Phase 1)
- [ ] Customer account creation and login (PHP sessions)
- [ ] Account dashboard — plan details, billing status, support tickets
- [ ] Contact form wired to database and email notification (PHPMailer)
- [ ] Admin panel — view and respond to contact submissions
- [ ] Password reset via email token

---

### Milestone 5 — Billing Integration
- [ ] Stripe payment integration for online bill pay
- [ ] Invoice generation and PDF download
- [ ] Recurring payment setup
- [ ] Payment history view in customer portal

---

### Milestone 6 — Network Status Page
- [ ] Public status page showing uptime and active incidents
- [ ] Admin interface to post and resolve incidents
- [ ] Automated uptime monitoring hook (Uptime Kuma or similar)
- [ ] Email/SMS notification for outages

---

### Milestone 7 — SEO, Performance & Security
- [ ] SSL/TLS configured end-to-end (Let's Encrypt via Nginx Proxy Manager)
- [ ] Sitemap.xml and robots.txt
- [ ] Open Graph and Twitter Card meta tags for social sharing
- [ ] Image optimization pipeline (WebP conversion on upload)
- [ ] Content Security Policy header tuned
- [ ] Security audit and pen test

---

### Milestone 8 — Operations & Automation
- [ ] Automated database backups to Unraid share via User Scripts cron
- [ ] Log rotation configured
- [ ] Staging environment (second compose stack on alternate ports)
- [ ] CI/CD pipeline — auto-deploy on push to `main` via webhook

---

## Updating the Site

Because `/mnt/cache/appdata/alwisp/www` is bind-mounted directly into `alwisp_web`, **PHP and asset changes take effect immediately** — no rebuild or restart needed.

```bash
# Pull latest code
cd /mnt/cache/appdata/alwisp
git pull origin main

# If the Dockerfile changed, rebuild the image and restart the web container:
docker build -t alwisp_web:latest /mnt/cache/appdata/alwisp
docker restart alwisp_web
```

The database container (`alwisp_db`) is completely independent — updates to the site never affect it.

---

## Useful Commands

```bash
# Rebuild the web image after Dockerfile changes
docker build -t alwisp_web:latest /mnt/cache/appdata/alwisp

# Start / stop individual containers
docker start alwisp_web
docker stop alwisp_web
docker restart alwisp_web

docker start alwisp_db
docker stop alwisp_db

# View live logs
docker logs -f alwisp_web
docker logs -f alwisp_db

# Open a shell inside the web container
docker exec -it alwisp_web bash

# Open a MySQL shell (use the DB container's br0 IP if connecting externally)
docker exec -it alwisp_db mysql -u alwisp_user -p alwisp

# Manual database backup
docker exec alwisp_db mysqldump -u alwisp_user -p alwisp > /mnt/cache/appdata/alwisp/backups/backup_$(date +%F).sql
```

---

## License

Proprietary — Alabama WISP LLC. All rights reserved.