Robert Helewka
b4d60f2f38
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.
193 lines
7.5 KiB
Markdown
193 lines
7.5 KiB
Markdown
# 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)
|