The Structs Postgres Database for Guild Operations
5.5K
Docker container for running the Structs Postgres Database.
Docker Hub: https://hub.docker.com/r/structs/structs-pg/
In the distant future the species of the galaxy are embroiled in a race for Alpha Matter, the rare and dangerous substance that fuels galactic civilization. Players take command of Structs, a race of sentient machines, and must forge alliances, conquer enemies and expand their influence to control Alpha Matter and the fate of the galaxy.
git clone [email protected]:playstructs/docker-structs-pg.git
cd docker-structs-pg
docker build .
The following will run the latest Structs postgres database server.
docker run -d --rm -p 5432:5432 --name=structs_pg structs/structs-pg:latest
A good way to run for development and for continual monitoring is to attach to the terminal:
docker run -it --rm -p 5432:5432 --name=structs_pg structs/structs-pg:latest
This image provides a persistent volume for /var/lib/postgresql if desired. If you wish to maintain the volume after the container is destroyed don't tell Docker to remove it with --rm. You can also override it:
docker run -d -p 5432:5432 -v /some/persistent/path:/var/lib/postgresql --name=structs_pg structs/structs-pg:latest
Stacks that also mount /etc/postgresql (config volume) must treat data and config volumes as a pair—see docs/postgres-volumes.md.
Use docker-compose.example.yml for recommended structs-pg / structs-pg-init settings:
database-start.sh) instead of a bash + tail -f wrapperstop_grace_period: 120s and memory limits aligned with POSTGRES_MEMORY_MBSQITCH_INIT_COMPLETE marker); set RUN_MIGRATIONS=1 to force sqitch from init| Topic | Doc |
|---|---|
| Volume pairing and memory env | docs/postgres-volumes.md |
Checkpoint / WAL failures, pg_resetwal | docs/postgres-recovery.md |
| Automatic main migrations, pinned staging and v0.22 recovery | docs/v022-migrations.md |
Environment variables (optional):
| Variable | Default | Purpose |
|---|---|---|
POSTGRES_MEMORY_MB | 8192 | Sets shared_buffers ≈ 25% via conf.d/structs-memory.conf |
POSTGRES_SHARED_BUFFERS | — | Overrides computed shared_buffers (e.g. 2048MB) |
POSTGRES_MAX_WAL_SIZE | 8GB | max_wal_size via conf.d/structs-wal.conf; pg_wal can grow to about this size on disk |
POSTGRES_MIN_WAL_SIZE | 1GB | min_wal_size |
POSTGRES_CHECKPOINT_TIMEOUT | 15min | checkpoint_timeout |
POSTGRES_WAL_COMPRESSION | lz4 | wal_compression (off, pglz, lz4, zstd) |
POSTGRES_SHUTDOWN_MODE | fast | pg_ctl stop -m mode on shutdown |
POSTGRES_SHUTDOWN_TIMEOUT | 115 | Seconds to wait for stop before Docker SIGKILL |
RUN_MIGRATIONS | 0 | Set to 1 on init container to force sqitch deploy |
Administering the database must be done from within the container. After starting the container you can perform the following to attach to its terminal and access the database:
docker ps
[note container id of the structs container]
docker exec -it [container id] /bin/bash
su structs -c "psql structs"
The primary configuration is handled in conf/sqitch.conf. Update this file prior to building to alter deployment.
Copyright 2021 Slow Ninja Inc.
Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
The sector-aware sync-state writer requires structs-pg's
planet-sector-20261110 migration before startup. Install both before the chain
backfill. See the writer contract.
Influence delivery additionally requires influence-grass-20261111. Sync-state
writes complete event frames transactionally after each changed block; deploy the
paired structs-grass outbox publisher to deliver them. Stop the previous writer
while applying this schema/writer upgrade. See sync-state/docs/influence-20261111.md.
The writer now labels grid attribute 15 as connectionCapacityMaximum, retains
exact uint64 values, and repairs mislabeled rows even when their value is unchanged.
Deploy structs-pg migration grid-connection-capacity-maximum-20261114 before
starting this writer. It adds the cap value constraint, legacy SQL ingestion,
label repair, and exact GRASS formatting. planet-sector-20261110 remains required.
The default STRUCTS_PG_REF pins b231d7ff7b856cfde0302260d73058a34dca3723,
which contains that migration. Push the structs-pg commit before building this
image so the build can fetch it. Custom schema pins must also contain the migration.
Do not deploy the updated writer with an image containing only the old schema.
Stop the old writer, migrate/verify, then start the new image before height 3,621,500.
Verification: go test ./... in sync-state; against an isolated migrated DB,
set INTEGRATION_DATABASE_URL and run go test ./internal/events -run 'TestHandler_GridConnectionCapacityMaximum|TestGridCapNotification' -v.
These tests cover exact values, label repair, idempotent replay, zero/deletion,
invalid values, and real PostgreSQL notification payloads.
Content type
Image
Digest
sha256:649eeaf8f…
Size
918.7 MB
Last updated
2 days ago
docker pull structs/structs-pg