Add full README with Unraid install guide, roadmap, and milestones
https://claude.ai/code/session_015wpwmheufcxkBuXivrSHhd
This commit is contained in:
Claude
327
README.md
327
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://<unraid-ip> → website
|
||||
http://<unraid-ip>: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.
|
||||
|
||||
Reference in New Issue
Block a user