From 83a6bd35c4479518bb4a5ebf2b5150000f96ef8d Mon Sep 17 00:00:00 2001 From: Claude Date: Sat, 28 Feb 2026 21:43:44 +0000 Subject: [PATCH] Add full README with Unraid install guide, roadmap, and milestones https://claude.ai/code/session_015wpwmheufcxkBuXivrSHhd --- README.md | 327 +++++++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 325 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index e10d3ae..4890f16 100644 --- a/README.md +++ b/README.md @@ -1,2 +1,325 @@ -# alwisp -HTML Server Container Pre-built for ALWISP +# 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 | + +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): + +```bash +cd /mnt/user/appdata +git clone https://github.com/jasonMPM/alwisp.git +cd alwisp +``` + +--- + +### Step 3 – Create your `.env` file + +```bash +nano .env +``` + +Paste and fill in real values: + +```env +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: + +```bash +cd /mnt/user/appdata/alwisp +docker compose up -d --build +``` + +--- + +### Step 5 – Verify containers are running + +```bash +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:// → website +http://:8080 → phpMyAdmin (optional, see below) +``` + +To start phpMyAdmin for database administration: + +```bash +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` +- [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 `./www` is bind-mounted directly into the container, **PHP and asset changes take effect immediately** — no rebuild needed. + +```bash +# 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 + +```bash +# 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.