Skip to content

Commit 74fc36b

Browse files
VonngVonng
committed
add docker deployment guide
1 parent 1125a45 commit 74fc36b

File tree

1 file changed

+330
-0
lines changed

1 file changed

+330
-0
lines changed

‎content/docs/setup/docker.md‎

Lines changed: 330 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,330 @@
1+
---
2+
title: Docker Deployment
3+
linkTitle: Docker
4+
weight: 258
5+
description: Spin up Pigsty in Docker containers for quick testing on macOS/Windows
6+
icon: fa-brands fa-docker
7+
module: [PIGSTY]
8+
categories: [Tutorial]
9+
---
10+
11+
12+
Pigsty is designed to run on native Linux, but can also run in Linux containers with systemd.
13+
If you don't have a native Linux env (e.g., **macOS** or **Windows** users), use Docker to quickly spin up a local single-node Pigsty for testing.
14+
15+
16+
----------------
17+
18+
## Summary
19+
20+
Enter the [**`docker/`**](https://github.com/pgsty/pigsty/tree/main/docker) directory in the Pigsty source and launch with one command:
21+
22+
```bash
23+
cd ~/pigsty/docker
24+
make launch # Start container + generate config + deploy
25+
```
26+
27+
After deployment, access services as follows:
28+
29+
| Service | URL / Command | Credentials |
30+
|:-----------|:-----------------------------------------------------------------|:-------------------|
31+
| SSH | `ssh root@localhost -p 2222` | Password: `pigsty` |
32+
| Web Portal | http://localhost:8080 | - |
33+
| Grafana | http://localhost:8080/ui | `admin` / `pigsty` |
34+
| PostgreSQL | `psql postgres://dbuser_dba:DBUser.DBA@localhost:5432/postgres` | `DBUser.DBA` |
35+
{.full-width}
36+
37+
{{% alert title="Web Portal & PostgreSQL Service" color="info" %}}
38+
Web Portal and PostgreSQL are only available after **Deployment** (`./deploy.yml`) completes.
39+
{{% /alert %}}
40+
41+
42+
----------------
43+
44+
## Prepare
45+
46+
Docker deployment requires:
47+
48+
| Item | Requirement | Item | Requirement |
49+
|:----------:|:------------------------------------|:--------:|:---------------------|
50+
| **Docker** | Docker 20.10+ (Desktop or CE) | **CPU** | At least 1 core |
51+
| **RAM** | At least 2GB | **Disk** | At least 20GB free |
52+
{.full-width}
53+
54+
55+
{{% alert title="Good Use Cases" color="success" %}}
56+
- Quick Pigsty experience on macOS/Windows without native Linux
57+
- Learning and testing Pigsty features, dev and debug
58+
- Quick local PostgreSQL dev environment
59+
{{% /alert %}}
60+
61+
{{% alert title="Not Recommended For" color="warning" %}}
62+
- **Production**: Container perf and stability are inferior to native Linux
63+
- **HA Clusters**: Docker single-node mode can't achieve multi-node HA
64+
- **Large Scale**: Use native Linux VMs or physical machines instead
65+
{{% /alert %}}
66+
67+
68+
----------------
69+
70+
## Launch
71+
72+
Pigsty provides out-of-the-box Docker support in the [**`docker/`**](https://github.com/pgsty/pigsty/tree/main/docker) source directory.
73+
74+
The simplest way is `make launch`, which auto-completes: start container, generate config, and deploy:
75+
76+
```bash
77+
cd ~/pigsty/docker
78+
make launch # One-liner: up + config + deploy
79+
```
80+
81+
Or step by step, allowing inspection and adjustment at each stage:
82+
83+
```bash
84+
cd ~/pigsty/docker
85+
make up # Start container
86+
make exec # Enter container
87+
./configure -c docker -g --ip 127.0.0.1 # Generate config
88+
./deploy.yml # Execute deployment
89+
```
90+
91+
To use locally built images instead of pulling from Docker Hub:
92+
93+
```bash
94+
cd ~/pigsty/docker
95+
make build # Build images locally
96+
make launch # Start container + generate config + deploy
97+
```
98+
99+
100+
----------------
101+
102+
## Config
103+
104+
Customize image version and port mappings by editing [**`.env`**](https://github.com/pgsty/pigsty/blob/main/docker/.env):
105+
106+
```bash
107+
# Image config
108+
PIGSTY_IMAGE=pgsty/pigsty # Image name: pgsty/linux, pgsty/admin, pgsty/infra, pgsty/pgsql, pgsty/pigsty
109+
PIGSTY_VERSION=v4.0.0 # Image tag, matches Pigsty version
110+
111+
# Port mappings (host ports)
112+
PIGSTY_SSH_PORT=2222 # SSH port
113+
PIGSTY_HTTP_PORT=8080 # Nginx HTTP port
114+
PIGSTY_HTTPS_PORT=8443 # Nginx HTTPS port
115+
PIGSTY_PG_PORT=5432 # PostgreSQL port
116+
```
117+
118+
**Port Mapping:**
119+
120+
| Env Var | Default | Container | Description |
121+
|:----------------------|:--------|:----------|:-------------------|
122+
| `PIGSTY_SSH_PORT` | `2222` | 22 | SSH access port |
123+
| `PIGSTY_HTTP_PORT` | `8080` | 80 | Nginx HTTP port |
124+
| `PIGSTY_HTTPS_PORT` | `8443` | 443 | Nginx HTTPS port |
125+
| `PIGSTY_PG_PORT` | `5432` | 5432 | PostgreSQL port |
126+
{.full-width}
127+
128+
Override ports via env vars if defaults are occupied:
129+
130+
```bash
131+
PIGSTY_HTTP_PORT=8888 docker compose up -d
132+
```
133+
134+
135+
----------------
136+
137+
## Images
138+
139+
Pigsty provides 5 layered Docker images, each building on the previous. Choose based on your needs:
140+
141+
| Image | Pull | Size | Contents | Use Case |
142+
|:---------------|:-------|:------|:--------------------------------|:-----------------|
143+
| `pgsty/linux` | ~150MB | 400MB | Debian 13 + systemd + SSH | Base container |
144+
| `pgsty/admin` | ~500MB | 1.3GB | + pig + Ansible + node packages | **Admin node** |
145+
| `pgsty/infra` | ~1.0GB | 2.7GB | + monitoring stack | Infra node |
146+
| `pgsty/pgsql` | ~1.2GB | 3.1GB | + PostgreSQL 18 core | PGSQL node |
147+
| `pgsty/pigsty` | ~1.6GB | 4.3GB | + all 340+ extensions | **Full Deploy** |
148+
{.full-width}
149+
150+
- **Pull**: Compressed transfer size when pulling from Docker Hub
151+
- **Size**: Uncompressed disk size after pulling
152+
- All images support **amd64** (x86_64) and **arm64** (Apple Silicon, AWS Graviton)
153+
- Image tags match Pigsty versions: `v4.0.0`, `latest`, etc.
154+
155+
**Image Hierarchy:**
156+
157+
```
158+
debian:trixie
159+
└── pgsty/linux (base + systemd + ssh)
160+
└── pgsty/admin (+ pig + ansible + node packages)
161+
└── pgsty/infra (+ monitoring stack)
162+
└── pgsty/pgsql (+ postgresql core)
163+
└── pgsty/pigsty (+ all extensions)
164+
```
165+
166+
167+
----------------
168+
169+
## Commands
170+
171+
Pigsty Docker provides rich Makefile commands for container and image management.
172+
173+
### Docker Compose
174+
175+
Recommended way to run. Common commands:
176+
177+
```bash
178+
make up # Start container
179+
make down # Stop and remove container
180+
make start # Start stopped container
181+
make stop # Stop container
182+
make restart # Restart container
183+
make pull # Pull latest image
184+
make config # Run ./configure in container
185+
make deploy # Run ./deploy.yml in container
186+
make launch # One-liner: up + config + deploy
187+
```
188+
189+
### Container Access
190+
191+
```bash
192+
make exec # Enter container bash
193+
make ssh # SSH into container
194+
make log # View container logs
195+
make status # View systemd status
196+
make ps # View process list
197+
make conf # View config file
198+
make pass # View passwords in config
199+
```
200+
201+
### Image Build
202+
203+
```bash
204+
make linux # Build pgsty/linux base image
205+
make admin # Build pgsty/admin admin node image
206+
make infra # Build pgsty/infra infra image
207+
make pgsql # Build pgsty/pgsql PostgreSQL image
208+
make pigsty # Build pgsty/pigsty full image
209+
make build # Build all 5 images (same as make images)
210+
make images # Build all 5 images
211+
```
212+
213+
### Image Push
214+
215+
```bash
216+
make pigsty-push # Push pgsty/pigsty image (multi-arch)
217+
make images-push # Push all images
218+
```
219+
220+
### Image Management
221+
222+
```bash
223+
make save # Export image to pigsty-<version>-<arch>.tgz
224+
make load # Import image from tgz file
225+
make rmi # Remove current version's pigsty image
226+
make rmi-all # Remove current version's all images
227+
```
228+
229+
### Cleanup
230+
231+
```bash
232+
make clean # Stop and remove container
233+
make purge # Remove container and wipe data (prompts for confirmation)
234+
```
235+
236+
237+
----------------
238+
239+
## Manual Run
240+
241+
If you prefer `docker run` over Docker Compose:
242+
243+
```bash
244+
mkdir -p /data/pigsty # Create data directory
245+
docker run -d --privileged --name pigsty \
246+
-p 2222:22 -p 8080:80 -p 5432:5432 \
247+
-v /data/pigsty:/data \
248+
pgsty/pigsty:v4.0.0
249+
docker exec -it pigsty /bin/bash
250+
./configure -c docker -g --ip 127.0.0.1
251+
./deploy.yml
252+
```
253+
254+
Or use Makefile's `make run`:
255+
256+
```bash
257+
make run # Start with docker run
258+
make exec # Enter container
259+
make clean # Stop and remove container
260+
make purge # Remove container and wipe data
261+
```
262+
263+
264+
----------------
265+
266+
## How It Works
267+
268+
Pigsty Docker images are based on **Debian 13 (Trixie)** with **systemd** as init system.
269+
This keeps service management inside the container consistent with native Linux, using `systemctl`.
270+
271+
Key features:
272+
273+
- **systemd support**: Full systemd running inside container for proper service management
274+
- **SSH access**: Pre-configured SSH service, root password is `pigsty`
275+
- **Privileged mode**: Requires `--privileged` to support systemd
276+
- **Data persistence**: Data persisted via `/data` volume mount
277+
- **Pre-installed software**: Full image includes PostgreSQL 18 and 340+ extensions
278+
279+
When running `./configure` inside the container, `-c docker` applies the Docker-optimized [**config template**](/docs/concept/iac/template/):
280+
281+
- Uses `127.0.0.1` as default IP address
282+
- Optimized for container environment
283+
284+
285+
----------------
286+
287+
## FAQ
288+
289+
### Container won't start
290+
291+
Ensure Docker is properly installed with sufficient resources allocated. On Docker Desktop, allocate at least 2GB RAM.
292+
Check for port conflicts, especially ports 22, 80, 443, 5432.
293+
294+
### Can't access services
295+
296+
Web Portal and PostgreSQL are only available after deployment completes. Ensure `./deploy.yml` finished successfully.
297+
Use `make status` to check service status inside container.
298+
299+
### Port conflicts
300+
301+
If default ports are occupied, override via `.env` file or env vars:
302+
303+
```bash
304+
PIGSTY_HTTP_PORT=8888 PIGSTY_PG_PORT=5433 docker compose up -d
305+
```
306+
307+
### Data persistence
308+
309+
Container data is mounted to `./data` by default. To wipe and start fresh:
310+
311+
```bash
312+
make purge # Remove container and wipe data (prompts for confirmation)
313+
```
314+
315+
### macOS performance
316+
317+
On macOS with Docker Desktop, performance is worse than native Linux due to virtualization overhead.
318+
This is expected—Docker deployment is for dev/testing. For production, use [**native Linux installation**](/docs/setup/install/).
319+
320+
321+
----------------
322+
323+
## More
324+
325+
- **Docker Hub**: https://hub.docker.com/r/pgsty/pigsty
326+
- **Source Directory**: https://github.com/pgsty/pigsty/tree/main/docker
327+
- **Quick Start**: [**Native Linux Installation**](/docs/setup/install/)
328+
- **Offline Installation**: [**Offline**](/docs/setup/offline/)
329+
- **Production Deployment**: [**Deployment Guide**](/docs/deploy/)
330+

0 commit comments

Comments
 (0)