Sign inSign up

structs/structs-pg

By structs

•Updated 2 days ago

The Structs Postgres Database for Guild Operations

Image
0

5.5K

structs/structs-pg repository overview

⁠docker-structs-pg

Docker⁠ container for running the Structs Postgres Database⁠.

Docker Hub: https://hub.docker.com/r/structs/structs-pg/⁠

⁠Structs

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.

⁠How to Build

git clone [email protected]:playstructs/docker-structs-pg.git
cd docker-structs-pg
docker build .

⁠How to Use this Image

⁠Quickstart

The following will run the latest Structs postgres database server.

docker run -d --rm -p 5432:5432 --name=structs_pg structs/structs-pg:latest

⁠Interactive

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

⁠Persistent volume

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⁠.

⁠Docker Compose

Use docker-compose.example.yml⁠ for recommended structs-pg / structs-pg-init settings:

  • Supervised entrypoint (database-start.sh) instead of a bash + tail -f wrapper
  • stop_grace_period: 120s and memory limits aligned with POSTGRES_MEMORY_MB
  • One-shot init (SQITCH_INIT_COMPLETE marker); set RUN_MIGRATIONS=1 to force sqitch from init

⁠Operations

TopicDoc
Volume pairing and memory envdocs/postgres-volumes.md⁠
Checkpoint / WAL failures, pg_resetwaldocs/postgres-recovery.md⁠
Automatic main migrations, pinned staging and v0.22 recoverydocs/v022-migrations.md⁠

Environment variables (optional):

VariableDefaultPurpose
POSTGRES_MEMORY_MB8192Sets shared_buffers ≈ 25% via conf.d/structs-memory.conf
POSTGRES_SHARED_BUFFERS—Overrides computed shared_buffers (e.g. 2048MB)
POSTGRES_MAX_WAL_SIZE8GBmax_wal_size via conf.d/structs-wal.conf; pg_wal can grow to about this size on disk
POSTGRES_MIN_WAL_SIZE1GBmin_wal_size
POSTGRES_CHECKPOINT_TIMEOUT15mincheckpoint_timeout
POSTGRES_WAL_COMPRESSIONlz4wal_compression (off, pglz, lz4, zstd)
POSTGRES_SHUTDOWN_MODEfastpg_ctl stop -m mode on shutdown
POSTGRES_SHUTDOWN_TIMEOUT115Seconds to wait for stop before Docker SIGKILL
RUN_MIGRATIONS0Set to 1 on init container to force sqitch deploy

⁠Administration

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"

⁠Configuration

⁠sqitch.conf

The primary configuration is handled in conf/sqitch.conf. Update this file prior to building to alter deployment.

⁠Learn more

⁠License

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.

⁠v0.23.0 planet sector writer

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.

⁠v0.23.0 connection capacity maximum writer

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.

Tag summary

Content type

Image

Digest

sha256:649eeaf8f…

Size

918.7 MB

Last updated

2 days ago

docker pull structs/structs-pg