326 lines
8.9 KiB
Markdown
326 lines
8.9 KiB
Markdown
# 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.
|