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
• Installation – Unraid
• Environment Variables
• Project Structure
• Roadmap & Milestones
• Updating the Site
• 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

All containers share a private alwisp_net bridge network. MySQL is never exposed to the internet — the web container reaches it via the internal hostname db. 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 in Unraid settings (Settings → Docker → Enable Docker: Yes)
• User Scripts plugin (recommended, for scheduled tasks)
• A share to store the project files (e.g. /mnt/user/appdata/alwisp)

---

Step 1 – Install the Compose Manager plugin

Unraid handles multi-container apps via the Docker Compose Manager plugin.

1. Open Apps (Community Applications)
2. Search for Docker Compose Manager
3. Click Install and let it complete

---

Step 2 – Clone the repository onto your Unraid share

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

cd /mnt/user/appdata
git clone https://github.com/jasonMPM/alwisp.git
cd alwisp

---

Step 3 – Create your .env file

nano .env

Paste and fill in real values:

DB_ROOT_PASS=your_secure_root_password
DB_NAME=alwisp
DB_USER=alwisp_user
DB_PASS=your_secure_db_password

Save with Ctrl+O, exit with Ctrl+X.

Important: Never commit .env to git. It is already listed in .gitignore.

---

Step 4 – Add the project to Docker Compose Manager

1. In the Unraid web UI, go to the Docker tab
2. Click Compose (added by the plugin)
3. Click Add New Stack
4. Set the name: alwisp
5. Set the compose file path: /mnt/user/appdata/alwisp/docker-compose.yml
6. Click Save
7. Click Start to build and launch all containers

Alternatively, start directly from the terminal:

cd /mnt/user/appdata/alwisp
docker compose up -d --build

---

Step 5 – Verify containers are running

docker ps --filter name=alwisp

You should see alwisp_web and alwisp_db both with status Up.

Open a browser and navigate to your Unraid server's IP:

http://<unraid-ip>       → website
http://<unraid-ip>:8080  → phpMyAdmin (optional, see below)

To start phpMyAdmin for database administration:

docker compose --profile tools up -d

---

Step 6 – Point a domain (optional)

If you have a domain and are running Nginx Proxy Manager on Unraid:

1. In Nginx Proxy Manager, add a Proxy Host
2. Forward hostname/IP: your Unraid server IP, port 80
3. Enable SSL via Let's Encrypt
4. SSL certificate files can be bind-mounted into the container at /etc/apache2/ssl/ — the volume mount ./docker/apache/ssl is already wired in docker-compose.yml

---

Recommended Unraid Share Settings

Setting	Value
Share path	/mnt/user/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

• Dockerized LAMP stack (PHP 8.2, Apache, MySQL 8.0)
• Front-controller PHP router
• Responsive site skeleton with brand design system
• Homepage: hero, stats bar, services preview, why section, coverage CTA
• Contact form with server-side validation
• Stub pages for all top-level routes (services, coverage, about, contact, 404)
• Security headers, OPcache, and Apache hardening
• 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 ./www is bind-mounted directly into the container, PHP and asset changes take effect immediately — no rebuild needed.

# Pull latest code
cd /mnt/user/appdata/alwisp
git pull origin main

# If Dockerfile or docker-compose.yml changed, rebuild:
docker compose up -d --build

# Rebuild only the web container without touching the database:
docker compose up -d --build web

---

Useful Commands

# Start all containers
docker compose up -d

# Start with phpMyAdmin (admin tools profile)
docker compose --profile tools up -d

# Stop all containers
docker compose down

# View live logs (all containers)
docker compose logs -f

# View logs for one container
docker compose logs -f web

# Restart just the web container
docker compose restart web

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

# Open a MySQL shell
docker exec -it alwisp_db mysql -u alwisp_user -p alwisp

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

---

License

Proprietary — Alabama WISP LLC. All rights reserved.