Skip to content

gigamaster/amp

BranchesTags

Repository files navigation

AMP Docker Angie, MariaDB, PHP, SSL

Overview

Amp Manager

AMP Manager — Angie, MariaDB and PHP

Docker-based Dev Stack with Trusted SSL for Windows

Overview

From Code Consumers to Stack Architects
One .local at a Time.

Because Knowing How the Stack Works
Beats Just Making It Work!

Overview 
📢 Overcome the architectural enclosure, it's just another form of control.
REM
> This stack is intentionally kept small and readable.  
> You can open every .bat file, every .conf file, every docker-compose.yml.  
> Change them > Break them > Fix them.  
> That is how you really learn.

Features

The juniors' reaction is common and understandable: they see React/TS/JS everywhere (frontend jobs, tutorials, hype), so when they read "MariaDB + PHP", their brain immediately translates it to "old-school LAMP stack, no modern JS, I can't use React". It sounds legit on the surface, but it's actually not a limitation at all, it's just a separation of concerns.

Overview

Stack Description
AMP-Manager Open utility to scaffold .local domains, and generate certificate + config
Angie Modern NGINX fork with HTTP/3 support, modules, and API stats
MariaDB version 10.++, MySQL-compatible
PHP version 8.3.++, common extensions: mysqli, pdo_mysql, gd, zip, etc.
CA / SSL HTTPS using mkcert for easy install a CA, and green lock all .local domains

Overview

Angie, MariaDB and PHP are just the backend. You can build a React, TypeScript, frontend that talks to it via APIs (REST or GraphQL).

  • Frontend: React/TS/Vite/whatever you're using
  • Backend: PHP (Laravel/Symfony or even plain) and MariaDB
  • They communicate with fetch/axios, exactly like Node/Express would

This is a popular stack: tons of real apps (WordPress APIs, Laravel + React dashboards, e-commerce sites) do exactly this.
You're not 'stuck' in PHP for the UI, you're just using it for server logic, auth, DB queries.

Tip

Learning PHP backend teaches you fundamentals (routing, middleware, security, SQL) that transfer to any backend language later.
So go ahead: write your React SPA, point it at PHP endpoints. Zero limitation, only more tools in your belt.

Overview

Quick Start

Your Local Dev Environment

Follow these steps in order to build your first project.

Prerequisites

  • Windows 10/11 (64-bit)
  • Docker Desktop (with WSL2 backend recommended)
  • Administrator privileges (for initial CA installation)

1. Preparation

  • Download:
    Clone the repository or download a release ZIP and extract it to a folder e.g. D:\amp\

Amp releases

git clone https://github.com/gigamaster/amp.git

  • Launch Docker:
    Open Docker Desktop and ensure the engine is running.

  • Boot the Stack:
    From amp folder (where docker-compose.yml lives), open a terminal and run:

docker compose up -d

2. First Run (One-Time Setup)

  1. Navigate to \amp\config\ folder
  2. Run AMP-MANAGER.bat triggers a dialog to allow execution,
    and UAC/elevation to administrator is required to create your CA
  3. Install your Certificate Authority before any domain.
    Menu [C] option [1] Reset CA Wizard (red)
  4. Click "Yes" when Windows Security dialog appears.

Note

AMP-MANAGER.bat runs as admin whenever you start a new project.
Takes 10 seconds to get a green-lock HTTPS site ready for development.

3. The AMP-MANAGER Setup

AMP-MANAGER.bat allows you to manage your environment.

  • On the first run, you install your Certificate Authority (CA)
    this allows your browser to trust your domain .local SSL
  • Add the default site: Select [N] New Domain and type angie
  • Follow prompts to create your first domain e.g. angie
    angie → becomes https://angie.local
    the domain angie.localcode> is your dashboard with server API status.
    Note that AMP-MANAGER automatically adds .local
  • optionally scaffolds new domain folder
  • generates the domain SSL .pem files
  • creates the server configuration.

Reload Angie Server from AMP-MANAGER to update the the server with your new site configuration, or restart the container from terminal:

docker restart angie

Tip

Keep AMP-MANAGER.bat handy on your desktop, run Create-shortcut.bat

4. Test Your Site

On AMP-MANAGER, Select [O] Open Browser to visit the default angie.local
or open your browser and go to https://angie.local, check ✅ Green lock!

The default domain is your Dashboard for documentation, health checks, and status monitoring.


anglie.local → preview [docs]


📂 Project Structure - Workflow

amp/
├── config/
│   └── AMP-MANAGER.bat  ← First run as Admin to manage domains/certs
├── www/
│   └── project.local/   ← Your project files (index.php/html here)
├── docker-compose.yml   ← Stack definition (Angie + MariaDB + PHP)
└── README.md

⚙️ Daily Usage

Command Description
docker compose up -d Start stack (run from project root)
docker compose down Stop stack
docker compose logs -f angie Live Angie logs
docker compose logs -f php Live PHP logs
docker compose restart angie Reload configs after domain changes

🔒 Domain Management - AMP-MANAGER.bat

Run config/AMP-MANAGER.bat Windows prompt as Administrator to:

  1. Add domain: Enter project → creates:

    • Certificate: config/certs/project.local.pem
    • Hosts entry: 127.0.0.1 project.local
    • Web root: www/project.local/
    • Angie config: config/angie-sites/project.local.conf
    • Auto-restart Angie + open browser (optional)

  2. Remove domain: Comments out hosts entry + optional cert cleanup
    (Backup saved as hosts.bak)

✅ No manual config needed — everything automated per workflow

Overall Workflow

How AMP-Manager enables local development

This diagram shows the high-level workflow a student follows when using AMP-Manager:

  • Launch amp-manager.bat
  • Tool checks the environment (required files, updates hosts file, starts containers, generates trusted local SSL certificate via mkcert)
  • Developer opens browser, requests project.local
  • OS hosts file redirects .local domain to Docker network (Angie proxy → PHP + MariaDB)

It illustrates the end-to-end user journey from starting the tool to reaching a working HTTPS site in the browser.

---
config:
  theme: 'base'
  themeVariables:
    primaryColor: '#1b417e'
    primaryTextColor: '#fff'
    primaryBorderColor: '#2457a8'
    lineColor: '#F8B229'
    secondaryColor: '#1e3363'
    secondaryBorderColor: '#ff9800'
    tertiaryColor: '#212527'
    tertiaryBorderColor: '#272727'
---
graph TD
    subgraph Windows_Host [Self-Host]
        Browser[Web Browser]
        HostsFile[Windows Hosts File]
        IDE[Native IDE / VS Code]
        Manager[AMP-Manager.bat]
    end

    subgraph Docker_Engine [Docker Engine]
        subgraph Angie_Container [Angie / Reverse Proxy]
            Vhost[Project.local.conf]
            SSL[SSL Certificates .pem]
        end
        subgraph PHP_Container [PHP-FPM 8.x]
            Code[PHP Execution Engine]
        end
        subgraph DB_Container [MariaDB]
            Data[(Project Data)]
        end
    end

    %% Interactions
    Manager --"1. Scaffolds"--> IDE
    Manager --"2. Updates"--> HostsFile
    Manager --"3. Generates"--> Vhost
    
    Browser --"Request Domain.local"--> HostsFile
    HostsFile --"Resolve 127.0.0.1"--> Angie_Container
    
    Vhost --"FastCGI Pass"--> PHP_Container
    IDE --"Bind Mount /www/"--> PHP_Container
    PHP_Container --"Internal DNS"--> DB_Container
    
    %% Styling
    style Manager fill:#da1e1e,stroke:#ff5742,stroke-width:2px
    style Angie_Container fill:#1b417e80,stroke:#0a6fc2
    style PHP_Container fill:#1b417e80,stroke:#0a6fc2
Loading

Fully portable to run from any drive (C:, D:, USB, network shares).

✅ No hardcoded paths — runs from wherever you unzip it
✅ Per-domain certificates — each project gets its own trusted HTTPS cert
✅ Beginner-friendly — one-click domain setup with green lock in browsers
✅ Production-like — mirrors real-world LEMP stack architecture

A bind mount is a Linux mechanism that mounts an existing file or directory tree from the host system into a new location, often used to map local host directories into Docker containers for direct, high-> performance file sharing and synchronization. It provides real-time, two-way updates between the host and the target, commonly used for development or sharing configuration files.

The Infrastructure Process Flow

Host and container relationship, bind mounts, local domain and certificate creation.

This diagram focuses on the technical process flow and file-system bridging that AMP-Manager sets up behind the scenes:

  • Host → bind mounts (editable project files + config visible on both sides)
  • Hosts file modification (myproject.local → container IP)
  • mkcert certificate generation + trust (.pem files mounted into Angie)
  • Angie (reverse proxy) handles HTTPS termination for all .local domains

It emphasizes how the local domain becomes trusted and resolvable, and how source code/config remains editable directly on the host machine.

---
config:
  theme: 'base'
  themeVariables:
    primaryColor: '#1b417e'
    primaryTextColor: '#fff'
    primaryBorderColor: '#2457a8'
    lineColor: '#F8B229'
    secondaryColor: '#1e3363'
    secondaryBorderColor: '#ff9800'
    tertiaryColor: '#212527'
    tertiaryBorderColor: '#272727'
---
graph TD
    A[Windows Host<br><font color=white>D:\amp\...</font>] -->|Editable Files| B[www/ - sites folders]
    A -->|Editable| C[config/angie-sites/ - *.conf]
    A -->|mkcert.exe| D[certs/ - .pem + -key.pem]

    subgraph Docker Compose Stack
        E[angie container<br>Ports 80/443 exposed]
        F[php-fpm container]
        G[db mariadb container]
    end

    B -->|bind mount rw| E
    B -->|bind mount rw| F
    C -->|bind mount ro| E
    D -->|bind mount ro| E

    Browser[Browser<br>https://project.local] -->|DNS: hosts| E
    E -->|fastcgi_pass| F
    F -->|MySQL| G

    style A fill:#da1e1e,stroke:#ff5742
    style Browser fill:#0069ae,stroke:#fff
Loading

The Directory Tree

Train the Architect Mindset – One Trusted .local Domain at a Time

Windows Host (D:\amp\...)
│                        
├─ Host Folders (code & configs — fully editable in IDE/Notepad)
│   ├── www/                     ← Web root (your sites: angie.local/, project.local/, ...)
│   ├── config/
│   │   ├── AMP-MANAGER.bat      ← Generates CA, SSL, Configs, and scaffolding
│   │   ├── angie-sites/         ← Angie vhost configs (*.local.conf) 
│   │   ├── certs/               ← SSL certs/keys (from mkcert)
│   │   ├── db-init/             # SQL bootstrap (root permissions/grants)
│   │   ├── mkcert.exe           # Mkcert command-line utility (CA and SSL)
│   │   ├── angie.conf           # Angie Server configuration (modules)
│   │   └── php.ini              ← PHP configuration, custom settings
│   ├── data/                    ← Database 
│   └── logs/                    ← Angie, DB, PHP & app logs
│
│   (You edit files here directly — no container copy/sync needed)
│                                   
├─ Docker Desktop (runs Linux VM underneath)
│   │                                                         
│   └─ Docker Compose (amp stack)
│       ├── Network (amp-network) ───────────────┐
│       │                                        │
│       ├── Volumes / Bind Mounts (host ↔ container mapping)
│       │   ├── D:\amp\www                →  /www (rw)             # Sites served from host
│       │   ├── D:\amp\config\angie-sites → /etc/angie/http.d (ro) # Angie reads your vhosts
│       │   ├── D:\amp\config\certs       → /etc/angie/certs (ro)  # SSL certs for Angie
│       │   └── D:\amp\logs               → /var/log/php (rw)      # (optional) Logs to host
│       │
│       ├── Services (containers)
│       │   ├── angie (docker.angie.software/angie:latest)
│       │   │   ├─ Ports: 80:80, 443:443    Browser → localhost → Angie
│       │   │   └─ Reads configs from /etc/angie/http.d/*.local.conf
│       │   │                                
│       │   ├── php (webdevops/php:8.3/8.4)
│       │   │   ├─ FPM listens on 9000/tcp (internal)
│       │   │   └─ Reads code from /www (your host files — live reload)
│       │   │                             
│       │   └── db (mariadb:10.11)
│       │       └─ Data persisted (bind mount D:\amp\data\)
│       │
│       └── Workflow arrows (simplified)
│
└─ Browser (https://angie.local / project.local)
    ↓ (DNS: hosts file or wildcard → 127.0.0.1)
    → Windows host ports 80/443 → Docker published ports → Angie container

💡 PHP Version Tip

PHP 8.3 official security support ended December 31, 2025. To switch versions:

  1. Edit docker-compose.yml: 
    services:
  php:
    # Change image tag:
    image: webdevops/php-nginx:8.2  # ← 8.1, 8.2, 8.3, 8.4 available
  2. Rebuild containers: 
    docker compose down
docker compose build --no-cache
docker compose up -d

Note

All versions include same extensions (mysqli, pdo_mysql, gd, zip, etc.)

🛠️ Troubleshooting

⚠️ Windows 11 Console Compatibility (Important)

AMP-MANAGER.bat is set to CP850, but encoded with Estonian ISO 8859-13 characters, and ANSI color sequences to render the UI. Microsoft as automated its Terminal on Windows 11, making the console host switch code pages or rendering modes the breaks the UI.

Try to close the Terminal, and reopen AMP-MANAGER to reset the Terminal settings.

🔸 Ports 80/443 already in use?

# Check what's using ports:
netstat -ano | findstr ":80"
netstat -ano | findstr ":443"

# Common culprits:
# - Skype → Settings → Advanced → uncheck "Use port 80/443"
# - IIS → Windows Features → uncheck "Internet Information Services"
# - Other dev tools (XAMPP, WSL2 nginx) → stop their services first

🔸 Can't edit hosts file?

From PowerShell (Admin):

notepad $env:windir\System32\drivers\etc\hosts

From normal PowerShell (opens Notepad as Admin):

Start-Process notepad.exe -Verb runas -ArgumentList "$env:windir\System32\drivers\etc\hosts"

🔸 Verify mkcert CA installed?

  1. Press Win+R → type certmgr.msc → Enter
  2. Navigate to: Trusted Root Certification Authorities → Certificates
  3. Look for issuer: mkcert <your-machine-name>\<your-username>

🔸 Certificate not trusted in Firefox?

Firefox uses its own certificate store:

  1. Find root CA: Run mkcert -CAROOT in config folder
  2. In Firefox: about:preferences#privacy → Certificates → View Certificates → Authorities → Import → rootCA.pem

🔸 Docker commands failing?

  • Ensure Docker Desktop is running (system tray icon visible)
  • Restart Docker Desktop if containers won't start
  • Check WSL2 integration: Docker Desktop → Settings → Resources → WSL Integration

🌐 Why .local Domains?

  • Officially reserved for local network use (RFC 6762)
  • Never resolves on public internet → safe for development
  • Works with mDNS/Bonjour on macOS/Linux (though Windows uses hosts file)

🚧 TODO

Desktop portable app

Portability: Entire stack works from any path — C:\amp, D:\projects\angie-amp, \USB\amp, etc. No configuration needed.

📜 License


Docker Dev Stack Angie MariaDB PHP
Made with ❤️ for simplicity and reliability

About

AMP: Angie, MariaDB, PHP, and SSL Docker Container for Windows

gigamaster.github.io/amp/

Topics

windows docker ssl server local docker-compose domain mariadb self-hosted ssl-certificate homelab php8 angie angie-docker

Resources

Readme

License

MIT license
Activity

Stars

1 star

Watchers

1 watching

Forks

0 forks
Report repository

Releases 1

Release v1.11.3 Latest
Mar 5, 2026

Contributors

Languages