Piratenbande Docs

Architecture

Piratenbande is a small WordPress/WooCommerce app with custom presentation and checkout behavior.

Runtime

  • WordPress runs directly on a NixOS server.
  • nginx serves piratenbande.de, hosen-flicken.de, and stage.piratenbande.de on prod.
  • The rehearsal host serves r.piratenbande.de and r.stage.piratenbande.de.
  • PHP-FPM serves both prod and stage.
  • MariaDB contains separate prod and stage databases.
  • Redis is available for WordPress object caching.
  • SMTP is provided by msmtp on the host.
  • A disposable rehearsal NixOS host can be used to test full-server config before production

    • import. It is not the same thing as the persistent WordPress stage instance.

The current deployed roots are:

/var/www/prod
/var/www/stage

Stage may bind-mount production uploads read-only:

/var/www/stage/wp-content/uploads -> /var/www/prod/wp-content/uploads

This saves disk space but means plugins that generate files under uploads, such as analytics or cache plugins, may not work correctly on stage.

Code Ownership

This repo should own:

  • Custom themes and child themes.
  • Site-specific mu-plugins.
  • Site-specific custom plugins.
  • WordPress-owned nginx snippets under apps/wordpress/nginx/, such as redirects.
  • WordPress operations under apps/wordpress/scripts/.
  • Cross-cutting health checks under health/.
  • Infrastructure scripts under infra/*/scripts/.
  • NixOS modules/templates for the host.

This repo should not own:

  • WordPress core.
  • Uploaded media.
  • Database dumps.
  • Secrets.
  • Generic third-party plugins, unless later pinned through a lockfile.

Theme Strategy

The existing site uses an Astra child theme. For the first migration, keep that as one deployable theme so the production behavior stays recognizable. Split the theme internally by feature area:

  • archive/category behavior
  • checkout and thank-you page behavior
  • email text and templates
  • product page behavior
  • scripts and fonts

Move behavior into a plugin only when it is not presentation-specific or when it needs to survive a future theme change.

Plugin Strategy

The Etsy reviews plugin is standalone and public-facing enough to live in its own repository. This monorepo can later consume it by release artifact, submodule, or Composer package. Until that is decided, do not bury it inside the site theme.

Infrastructure Strategy

The NixOS config belongs in the repo as the source of reviewable knowledge, but the host should not blindly import the repo. The deployment path should always check and dry-activate first, then require an explicit switch step. Keep real secrets on the host or in a dedicated secret manager, and keep templates in infra/.

NixOS changes are deployed through a different path than WordPress code:

task test:nixos:check
task deploy:nixos:rehearsal
task deploy:nixos:prod
CONFIRM_NIXOS_PROD=prod task deploy:nixos:prod -- --apply

WordPress app code, app-owned nginx snippets, and operations live under apps/wordpress/.