docs: rewrite README with structured overview and quick start guide
Replaces the minimal project description with a comprehensive README including a component overview table, quick start instructions, common Ansible operations, and links to detailed documentation. Aligns with Red Panda Approval™ standards.
This commit is contained in:
192
docs/pgadmin.md
Normal file
192
docs/pgadmin.md
Normal file
@@ -0,0 +1,192 @@
|
||||
# PgAdmin - PostgreSQL Web Administration
|
||||
|
||||
## Overview
|
||||
|
||||
PgAdmin 4 is a web-based administration and management tool for PostgreSQL. It is deployed on **Portia** alongside the shared PostgreSQL instance, providing a graphical interface for database management, query execution, and server monitoring across both PostgreSQL deployments (Portia and Titania).
|
||||
|
||||
**Host:** portia.incus
|
||||
**Role:** database
|
||||
**Container Port:** 80 (Apache / pgAdmin4 web app)
|
||||
**External Access:** https://pgadmin.ouranos.helu.ca/ (via HAProxy on Titania, proxied through host port 25555)
|
||||
|
||||
## Architecture
|
||||
|
||||
```
|
||||
┌──────────┐ ┌────────────┐ ┌──────────────────────────────────┐
|
||||
│ Client │─────▶│ HAProxy │─────▶│ Portia │
|
||||
│ │ │ (Titania) │ │ │
|
||||
│ │ │ :443 │ │ :25555 ──▶ :80 (Apache) │
|
||||
└──────────┘ └────────────┘ │ │ │
|
||||
│ ┌────▼─────┐ │
|
||||
│ │ PgAdmin4 │ │
|
||||
│ │ (web) │ │
|
||||
│ └────┬─────┘ │
|
||||
│ │ │
|
||||
│ ┌────────▼────────┐ │
|
||||
│ │ PostgreSQL 17 │ │
|
||||
│ │ (localhost) │ │
|
||||
│ └─────────────────┘ │
|
||||
└──────────┬─────────────────────┘
|
||||
│ SSL
|
||||
▼
|
||||
┌─────────────────────┐
|
||||
│ PostgreSQL 17 (SSL) │
|
||||
│ (Titania) │
|
||||
└─────────────────────┘
|
||||
```
|
||||
|
||||
PgAdmin connects to:
|
||||
- **Portia's PostgreSQL** — locally via `localhost:5432` (no SSL)
|
||||
- **Titania's PostgreSQL** — over the Incus network via SSL, using the fetched certificate stored at `/var/lib/pgadmin/certs/titania-postgres-ca.crt`
|
||||
|
||||
## Terraform Resources
|
||||
|
||||
### Host Definition
|
||||
|
||||
PgAdmin runs on Portia, defined in `terraform/containers.tf`:
|
||||
|
||||
| Attribute | Value |
|
||||
|-----------|-------|
|
||||
| Image | noble |
|
||||
| Role | database |
|
||||
| Security Nesting | false |
|
||||
| Proxy Devices | `25555 → 80` (Apache/PgAdmin web UI) |
|
||||
|
||||
The Incus proxy device maps host port 25555 to Apache on port 80 inside the container, where PgAdmin4 is served as a WSGI application.
|
||||
|
||||
## Ansible Deployment
|
||||
|
||||
### Playbook
|
||||
|
||||
```bash
|
||||
cd ansible
|
||||
ansible-playbook pgadmin/deploy.yml
|
||||
```
|
||||
|
||||
### Files
|
||||
|
||||
| File | Purpose |
|
||||
|------|---------|
|
||||
| `pgadmin/deploy.yml` | PgAdmin installation and SSL cert distribution |
|
||||
|
||||
### Deployment Steps
|
||||
|
||||
1. **Add PgAdmin repository** — Official pgAdmin4 APT repository with GPG key
|
||||
2. **Install PgAdmin** — `pgadmin4-web` package (includes Apache configuration)
|
||||
3. **Create certs directory** — `/var/lib/pgadmin/certs/` owned by `www-data`
|
||||
4. **Fetch Titania SSL certificate** — Retrieves the self-signed PostgreSQL SSL cert from Titania
|
||||
5. **Distribute certificate** — Copies to `/var/lib/pgadmin/certs/titania-postgres-ca.crt` for SSL connections
|
||||
|
||||
### ⚠️ Manual Post-Deployment Step Required
|
||||
|
||||
After running the playbook, you **must** SSH into Portia and run the PgAdmin web setup script manually:
|
||||
|
||||
```bash
|
||||
# SSH into Portia
|
||||
ssh portia.incus
|
||||
|
||||
# Run the setup script
|
||||
sudo /usr/pgadmin4/bin/setup-web.sh
|
||||
```
|
||||
|
||||
This interactive script:
|
||||
- Prompts for the **admin email address** and **password** (use the values from `pgadmin_email` and `pgadmin_password` vault variables)
|
||||
- Configures Apache virtual host for PgAdmin4
|
||||
- Sets file permissions and ownership
|
||||
- Restarts Apache to activate the configuration
|
||||
|
||||
This step cannot be automated via Ansible because the script requires interactive input and performs Apache configuration that depends on the local environment.
|
||||
|
||||
### Variables
|
||||
|
||||
#### Host Variables (`host_vars/portia.incus.yml`)
|
||||
|
||||
| Variable | Description |
|
||||
|----------|-------------|
|
||||
| `pgadmin_user` | System user (`pgadmin`) |
|
||||
| `pgadmin_group` | System group (`pgadmin`) |
|
||||
| `pgadmin_directory` | Data directory (`/srv/pgadmin`) |
|
||||
| `pgadmin_port` | External port (`25555`) |
|
||||
| `pgadmin_email` | Admin login email (`{{ vault_pgadmin_email }}`) |
|
||||
| `pgadmin_password` | Admin login password (`{{ vault_pgadmin_password }}`) |
|
||||
|
||||
#### Vault Variables (`group_vars/all/vault.yml`)
|
||||
|
||||
| Variable | Description |
|
||||
|----------|-------------|
|
||||
| `vault_pgadmin_email` | PgAdmin admin email address |
|
||||
| `vault_pgadmin_password` | PgAdmin admin password |
|
||||
|
||||
## Configuration
|
||||
|
||||
### SSL Certificate for Titania Connection
|
||||
|
||||
The playbook fetches the self-signed PostgreSQL SSL certificate from Titania and places it at `/var/lib/pgadmin/certs/titania-postgres-ca.crt`. When adding Titania's PostgreSQL as a server in PgAdmin:
|
||||
|
||||
1. Navigate to **Servers → Register → Server**
|
||||
2. On the **Connection** tab:
|
||||
- Host: `titania.incus`
|
||||
- Port: `5432`
|
||||
- Username: `postgres`
|
||||
3. On the **SSL** tab:
|
||||
- SSL mode: `verify-ca` or `require`
|
||||
- Root certificate: `/var/lib/pgadmin/certs/titania-postgres-ca.crt`
|
||||
|
||||
### Registered Servers
|
||||
|
||||
After setup, register both PostgreSQL instances:
|
||||
|
||||
| Server Name | Host | Port | SSL |
|
||||
|-------------|------|------|-----|
|
||||
| Portia (local) | `localhost` | `5432` | Off |
|
||||
| Titania (Casdoor) | `titania.incus` | `5432` | verify-ca |
|
||||
|
||||
## Operations
|
||||
|
||||
### Start/Stop
|
||||
|
||||
```bash
|
||||
# PgAdmin runs under Apache
|
||||
sudo systemctl start apache2
|
||||
sudo systemctl stop apache2
|
||||
sudo systemctl restart apache2
|
||||
```
|
||||
|
||||
### Health Check
|
||||
|
||||
```bash
|
||||
# Check Apache is serving PgAdmin
|
||||
curl -s -o /dev/null -w "%{http_code}" http://localhost/pgadmin4/login
|
||||
|
||||
# Check from external host
|
||||
curl -s -o /dev/null -w "%{http_code}" http://portia.incus/pgadmin4/login
|
||||
```
|
||||
|
||||
### Logs
|
||||
|
||||
```bash
|
||||
# Apache error log
|
||||
tail -f /var/log/apache2/error.log
|
||||
|
||||
# PgAdmin application log
|
||||
tail -f /var/log/pgadmin/pgadmin4.log
|
||||
```
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Common Issues
|
||||
|
||||
| Symptom | Cause | Resolution |
|
||||
|---------|-------|------------|
|
||||
| 502/503 on pgadmin.ouranos.helu.ca | Apache not running on Portia | `sudo systemctl restart apache2` on Portia |
|
||||
| Login page loads but can't authenticate | Setup script not run | SSH to Portia and run `sudo /usr/pgadmin4/bin/setup-web.sh` |
|
||||
| Can't connect to Titania PostgreSQL | Missing SSL certificate | Re-run `ansible-playbook pgadmin/deploy.yml` to fetch cert |
|
||||
| SSL certificate error for Titania | Certificate expired or regenerated | Re-fetch cert by re-running the playbook |
|
||||
| Port 25555 unreachable | Incus proxy device missing | Verify proxy device in `terraform/containers.tf` for Portia |
|
||||
|
||||
## References
|
||||
|
||||
- [PgAdmin 4 Documentation](https://www.pgadmin.org/docs/pgadmin4/latest/)
|
||||
- [PostgreSQL Deployment](postgresql.md)
|
||||
- [Terraform Practices](terraform.md)
|
||||
- [Ansible Practices](ansible.md)
|
||||
Reference in New Issue
Block a user