Applications

• 1: Enterprise Self-Hosted Supabase
• 2: Odoo: Self-Hosted Open Source ERP
• 3: Dify: AI Workflow Platform
• 4: InsForge: AI Backend-as-a-Service
• 5: Hindsight: AI Long-Term Memory
• 6: FerretDB: MongoDB Protocol
• 7: Teable: AI No-Code Database
• 8: Gitea: Self-Hosted Git Service
• 9: NocoDB: Open-Source Airtable
• 10: Mattermost: Open-Source Team Collaboration
• 11: Wiki.js: OSS Wiki Software
• 12: Maybe: Self-Hosted Personal Finance
• 13: Immich: Self-Hosted Photo and Video Library
• 14: Kong: API Gateway
• 15: Metabase: BI Analytics Tool
• 16: Registry: Container Image Cache
• 17: JumpServer: Open-Source Bastion Host
• 18: ByteBase: Schema Migration
• 19: pgAdmin: PostgreSQL GUI
• 20: PGWeb: Browser-based PostgreSQL Client
• 21: PostgREST: Auto-Generated API
• 22: Electric: PostgreSQL Sync Engine
• 23: Jupyter: Notebooks and Data Analysis
• 24: PGLOG: PostgreSQL Log Analysis Application
• 25: NOAA ISD Global Weather Station Historical Data Query
• 26: WHO COVID-19 Pandemic Dashboard
• 27: StackOverflow Global Developer Survey
• 28: DB-Engines Database Popularity Trend Analysis
• 29: AWS & Aliyun Server Pricing

curl -fsSL https://repo.pigsty.io/get | bash; cd ~/pigsty
./bootstrap
./configure -c <template>     # e.g. app/dify, app/immich, app/jumpserver, app/maybe, supabase
vi pigsty.yml                 # edit passwords, domains, IPs, and secrets
./deploy.yml                  # deploy infrastructure and databases
./docker.yml                  # install Docker
./app.yml                     # launch applications

cd ~/pigsty/app/<name>
make up

./app.yml -e app=<name>

1 - Enterprise Self-Hosted Supabase

Pigsty can deploy Supabase on your physical, virtual, or cloud servers with a single command. Self-hosting provides more extensions, performance options, control, and potential cost savings.

As of August 2026, the official Supabase self-hosting guide recommends Docker and classifies other implementations as community projects. Pigsty is an independent community integration and is not currently listed on that page.

This tutorial requires basic Linux knowledge. Otherwise, consider using Supabase cloud or plain Docker Compose self-hosting.

The current template tracks the coordinated Supabase self-hosted/v0.8.2 release (commit 564eab8), with Envoy 1.39.1 as the default gateway and Studio 2026.09.07-sha-7996410. It uses external Pigsty-managed PostgreSQL, with PG18 as the template default. This combination has passed basic functional checks on PG18.6. See docker-compose.yml for the complete image versions and the upgrade procedure for existing deployments.

TL;DR

Prepare a Linux server, follow the Pigsty standard single-node installation process with the supabase config template:

curl -fsSL https://repo.pigsty.io/get | bash; cd ~/pigsty
./configure -c supabase    # Use supabase config (change credentials in pigsty.yml)
vi pigsty.yml              # Edit domain, passwords, keys...
./deploy.yml               # Standard single-node Pigsty deployment
./docker.yml -l supabase   # Install Docker on the supabase group
./app.yml -l supabase      # Start stateless containers on the supabase group (may be slow)

After installation, access Supa Studio on port 8000 with username supabase and password pigsty.

demo/supabase.cast — /demo/supabase.cast

Checklist

• At least one 2-core/4 GB server; 4 cores/8 GB or more is recommended for the full stack
• Static internal IPv4 address
• Supported Linux distro installed
• Standard Pigsty installation
• Modified config file: domain, passwords, IP address
• Docker module installed, ensure proxy/mirror available
• Use Pigsty’s app.yml to start Supabase

Table of Contents

• What is Supabase?
• Why Self-Host?
• Single-Node Quick Start
• Upgrading Existing Deployments
• Advanced: Security Hardening
• Advanced: Domain Configuration
• Advanced: External Object Storage
• Advanced: Using SMTP
• Advanced: True High Availability

What is Supabase?

Supabase is an open-source Backend as a Service (BaaS) and Firebase alternative. It is widely used for AI agent database and backend services. Supabase adds authentication, messaging, edge functions, and object storage to PostgreSQL. It generates REST APIs from the database schema. Enable pg_graphql when you need GraphQL APIs.

Supabase combines backend services to reduce development and infrastructure maintenance work. Developers can focus on database design and the frontend to build applications quickly. Vibe coding can help create the frontend and schema for complete applications.

Supabase is one of the most popular open-source projects in the PostgreSQL ecosystem. As of August 2026, its GitHub repository has more than 100,000 stars. Supabase also offers a free hosted tier. The current Free plan includes shared CPU, 500 MB of RAM, a 500 MB database quota, and 1 GB of file storage; consult the official page for later changes.

Why Self-Host?

Self-hosting can address cost, functionality, and control requirements.

Costs can rise quickly when data, compute, or availability requirements exceed a managed-service tier. See Is Cloud Database an IQ Tax?. Reliable local enterprise NVMe SSDs have a cost advantage of three to four orders of magnitude over cloud storage. Self-hosting can use this advantage.

Functionality is another reason. Multi-tenant security and licensing constraints exclude many PostgreSQL extensions from cloud services. Although extensions are a core PostgreSQL feature, Supabase promises more than 50 preconfigured extensions. The exact list changes with platform releases. Self-hosting with Pigsty provides up to 600 ready-to-use extensions.

Self-hosting gives users control and helps avoid vendor lock-in. Supabase aims to provide an open-source Firebase alternative without vendor lock-in, but enterprise self-hosting still requires work. Supabase develops and maintains PostgreSQL extensions. It acquired the Oriole team in 2024 and offers OrioleDB as an optional Public Alpha. OrioleDB is not the production default or a confirmed replacement for native PostgreSQL. Some Supabase extensions and patched kernels are absent from the official PGDG repository.

Missing packages create a dependency on the supabase/postgres Docker image for self-hosting. Pigsty provides these packages for other deployment methods. The 10 missing Supabase extensions are available as RPM/DEB packages for the supabase template matrix. This covers EL 8/9, Debian 12, and Ubuntu 22.04/24.04/26.04 on x86_64 and aarch64. See supported Linux distributions.

Supabase deployments install most extensions by default. Enable them as needed. Newer templates install the pg_graphql package without creating its extension object. For GraphQL APIs, run CREATE EXTENSION IF NOT EXISTS pg_graphql; in the target database. The template event trigger rebuilds graphql_public.graphql and its permissions.

Pigsty manages the highly available PostgreSQL and Silo object storage clusters. It also manages Docker, the Nginx reverse proxy, domains, and HTTPS certificates. Run any number of stateless Supabase container clusters with Docker Compose. Store their state in external Pigsty-managed database services.

The current template supports PostgreSQL 15-18, with 18 as the default. You can install 600 extensions and scale Supabase, PostgreSQL, and Silo independently. You are responsible for operating and securing this infrastructure.

Single-Node Quick Start

Start with single-node deployment. Multi-node high availability is covered later.

Prepare a fresh Linux server, use the Pigsty supabase configuration template for standard installation, then run docker.yml and app.yml to start stateless Supabase containers (Envoy uses HTTP port 8000 by default; the Nginx portal provides HTTPS).

curl -fsSL https://repo.pigsty.io/get | bash; cd ~/pigsty
./configure -c supabase    # Use supabase config (change credentials in pigsty.yml)
vi pigsty.yml              # Edit domain, passwords, keys...
./deploy.yml               # Install Pigsty
./docker.yml -l supabase   # Install Docker on the supabase group
./app.yml -l supabase      # Start stateless containers on the supabase group

Before deploying Supabase, modify the auto-generated pigsty.yml configuration file (domain and passwords) according to your needs. For local development/testing, you can skip this and customize later.

If configured correctly, after about ten minutes, you can access the Supabase Studio GUI at http://<your_ip_address>:8000 on your local network. Default username and password are supabase and pigsty.

Notes:

• In mainland China, Pigsty uses 1Panel and 1ms DockerHub mirrors by default, which may be slow.
• You can configure your own proxy and registry mirror, then manually pull images with cd /opt/supabase; make pull. Before exporting offline images, run make pull and then make save. The complete bundle includes both the default Envoy and optional Kong gateways. We also offer expert consulting services including complete offline installation packages.
• If you need object storage functionality, you must access Supabase via domain and HTTPS, otherwise errors will occur.
• For serious production deployments, always change all default passwords!

Key Technical Decisions

Here are some key technical decisions for self-hosting Supabase:

Single-node deployment does not provide PostgreSQL/Silo high availability. Compared with the official Docker Compose setup, it provides monitoring, extension installation, independent component scaling, and point-in-time recovery.

Pigsty’s Supabase template does not start the upstream Compose db or supavisor containers, and does not use Supabase’s bundled connection pooler. Stateless containers connect directly to the PostgreSQL service managed by Pigsty; the single-node template uses service port 5436 by default, which always routes to the current primary.

Logflare / Analytics uses _analytics in the separate _supabase database instead of postgres._analytics in the application database. This keeps internal tables such as oban_jobs and oban_peers out of the project database’s public schema. It prevents Supabase Advisor RLS warnings about those tables. LOGFLARE_DB and LOGFLARE_SCHEMA control these locations.

The Query Performance page in Supabase Studio accesses pg_stat_statements with a public, extensions search path. Pigsty keeps the pg_stat_statements extension objects in the monitor schema for compatibility with pg_exporter and existing monitoring dashboards. The template creates a compatibility view and functions in the extensions schema for Studio.

Envoy is the default gateway, under the Compose service name api-gw. Kong 3.9.3 remains available as a transition option. To enable Kong, run this combination from the application directory:

docker compose -f docker-compose.yml -f docker-compose.kong.yml up -d

Both gateways use API_GW_HTTP_PORT for their HTTP port, defaulting to 8000. Only the Kong configuration also exposes KONG_HTTPS_PORT (default 8443).

For one server or cloud-hosted servers, Pigsty recommends external S3 instead of local Silo for PostgreSQL backups and Supabase Storage. This supports recovery on an hour scale after single-node failure. Actual RPO depends on the latest recoverable backup, WAL archives, and object-storage availability. The topology does not guarantee a fixed RPO.

For production, Pigsty recommends at least 3-4 nodes with multi-node high availability for Silo and PostgreSQL. This requires more nodes and disks. Update pigsty.yml and Supabase configuration to use high-availability endpoints.

Some Supabase features require sending emails, so SMTP service is needed. Unless purely for internal use, production deployments should use SMTP cloud services. Self-hosted mail servers’ emails are often marked as spam.

If your service is directly exposed to the public internet, we strongly recommend using real domain names and HTTPS certificates via Nginx Portal.

Next, we’ll discuss advanced topics for improving Supabase security, availability, and performance beyond single-node deployment.

Upgrading Existing Deployments

Back up PostgreSQL, object storage, and application volumes, and review local customizations before upgrading. The old gateway service was named kong; the new service is api-gw. Before replacing the old Compose files, run docker compose down in the old application directory, without -v. This stops the old gateway and releases its ports while preserving volumes and external data. Running only up -d with the new files can leave the old kong container behind and cause port or container-name conflicts.

files/supabase.sql is a fresh-install baseline. Do not replay it over an existing database. Updating containers alone does not apply new SQL grants or remove old database settings. Version 0.8.2 removes the SQL-visible app.settings.jwt_secret and PostgREST’s PGRST_APP_SETTINGS_JWT_SECRET. Application-level JWT verification settings and app.settings.jwt_exp remain in place.

First review custom SQL functions that depend on current_setting('app.settings.jwt_secret'). If they still need a signing key, migrate them to a restricted Vault secret as described in the upstream migration guidance. Allow only the function owner to read it, and avoid exposing the decrypted key through a public RPC.

After handling these dependencies and backing up the database, run from the Pigsty installation root, connect to the target Supabase database as an administrator, and apply the idempotent narrow upgrade script:

psql -X -v ON_ERROR_STOP=1 -d '<target-supabase-database>' -f files/supabase-0.8.2.sql

The script resets only the old database-level secret setting in the current database and grants the webhook owner supabase_functions_admin USAGE on the extensions schema. It preserves JWT expiration and existing data. Also remove the old parameter from the deployment inventory, update Compose, and recreate PostgREST. If you injected the same secret through ALTER ROLE, server settings, or session SQL, review and remove those sources separately. Existing connections may retain the old value. Reconnect and verify as an ordinary application role in a new session without printing the secret:

SELECT nullif(current_setting('app.settings.jwt_secret', true), '') IS NULL
       AS jwt_secret_removed;
SELECT has_schema_privilege('supabase_functions_admin', 'extensions', 'USAGE')
       AS webhook_extensions_usage;

For older deployments, also check that supabase_storage_admin has CREATE on the target database and that the upstream 2026-07-30 pg_cron privilege migration has been applied. See the template upgrade notes for the checks and remedies. Fresh-install and same-version container recreation tests do not replace an upgrade rehearsal for an existing application database.

Advanced: Security Hardening

Pigsty Components

For production, changing Pigsty component passwords is strongly recommended. These defaults are public:

• grafana_admin_password: pigsty, Grafana admin password
• pg_admin_password: DBUser.DBA, PostgreSQL superuser password
• pg_monitor_password: DBUser.Monitor, PostgreSQL monitoring user password
• pg_replication_password: DBUser.Replicator, PostgreSQL replication user password
• patroni_password: Patroni.API, Patroni HA component password
• haproxy_admin_password: pigsty, Load balancer admin password
• minio_secret_key: S3User.MinIO, Silo root user secret
• etcd_root_password: Etcd.Root, ETCD root user password
• Additionally, strongly recommend changing the PostgreSQL business user password for Supabase, default is DBUser.Supa

These are Pigsty component passwords. Strongly recommended to set before installation.

Supabase Keys

Besides Pigsty component passwords, you need to change Supabase keys, including:

• JWT_SECRET: JWT signing key, at least 32 characters
• ANON_KEY: Anonymous user JWT credential
• SERVICE_ROLE_KEY: Service role JWT credential
• SUPABASE_PUBLISHABLE_KEY / SUPABASE_SECRET_KEY: New opaque API keys, can be left empty if not enabled
• JWT_KEYS / JWT_JWKS: Asymmetric JWT keys and JWKS, can be left empty if not enabled
• ANON_KEY_ASYMMETRIC / SERVICE_ROLE_KEY_ASYMMETRIC: Asymmetric signing JWTs, can be left empty if not enabled
• PG_META_CRYPTO_KEY: PostgreSQL Meta service encryption key, at least 32 characters
• SECRET_KEY_BASE: Random secret used by Realtime
• REALTIME_DB_ENC_KEY: Realtime database encryption key
• DASHBOARD_USERNAME: Supabase Studio web UI default username, default supabase
• DASHBOARD_PASSWORD: Supabase Studio web UI default password, default pigsty
• LOGFLARE_PUBLIC_ACCESS_TOKEN: Logflare public access token, at least 32 random characters
• LOGFLARE_PRIVATE_ACCESS_TOKEN: Logflare private access token, at least 32 random characters
• LOGFLARE_DB / LOGFLARE_SCHEMA: Internal database and schema used by Logflare / Analytics, defaulting to _supabase / _analytics

Please follow the Supabase tutorial: Securing your services:

• Generate a JWT_SECRET with at least 40 characters, then use the tutorial tools to issue ANON_KEY and SERVICE_ROLE_KEY JWTs.
• Use the tutorial tools to generate an ANON_KEY JWT based on JWT_SECRET and expiration time — this is the anonymous user credential.
• Use the tutorial tools to generate a SERVICE_ROLE_KEY — this is the higher-privilege service role credential.
• If you use newer opaque API keys or asymmetric JWTs, also generate and fill SUPABASE_PUBLISHABLE_KEY, SUPABASE_SECRET_KEY, JWT_KEYS, JWT_JWKS, and the corresponding asymmetric ANON_KEY / SERVICE_ROLE_KEY.
• Specify a random string of at least 32 characters for PG_META_CRYPTO_KEY to encrypt Studio UI and meta service interactions.
• SECRET_KEY_BASE must be at least 64 characters; REALTIME_DB_ENC_KEY must be exactly 16 characters.
• Generate separate random credentials for S3_PROTOCOL_ACCESS_KEY_ID and S3_PROTOCOL_ACCESS_KEY_SECRET; do not reuse an object-storage administrator password.
• If using different PostgreSQL business user passwords, modify POSTGRES_PASSWORD accordingly.
• If your object storage uses different passwords, modify S3_ACCESS_KEY and S3_SECRET_KEY accordingly.
• If Edge Functions are exposed to untrusted clients, set FUNCTIONS_VERIFY_JWT to true as needed.
• API_EXTERNAL_URL should now be the external Auth service URL, retaining the /auth/v1 suffix, for example https://supa.pigsty.io/auth/v1; keep SITE_URL and SUPABASE_PUBLIC_URL at the site root URL.
• The current template defaults PGRST_DB_SCHEMAS to public,graphql_public; the storage schema is used by the Storage API and is no longer exposed through PostgREST by default.

To enable asymmetric authentication, configure JWT_KEYS, JWT_JWKS, and all four opaque/asymmetric API-key variables together, then enable the corresponding Compose override. Without the override, the default remains HS256:

docker compose -f docker-compose.yml -f docker-compose.asymmetric.yml up -d

If you also select Kong, insert -f docker-compose.kong.yml before -f docker-compose.asymmetric.yml. Use the same override combination for subsequent starts and updates. Edge Functions receive JWT_JWKS through SUPABASE_JWKS and fall back to HS256 when it is empty. Update the worker together with the shared volumes/functions/deno.jsonc import map to support @supabase/functions-js, @supabase/server, and the per-request SUPABASE_FUNCTION_SLUG. See the pinned source notes.

After changing Supabase credentials, update configuration and recreate the containers. The commands below and later startup examples without Compose overrides apply only to the default Envoy + HS256 stack:

./app.yml -l supabase -t app_config,app_launch   # Using playbook
cd /opt/supabase; make up            # Manual execution

For Kong or asymmetric JWTs, first update configuration with ./app.yml -l supabase -t app_config, then enter /opt/supabase and run up -d with the same -f file combination shown above to retain the gateway and JWT overrides.

Advanced: Domain Configuration

If using Supabase locally or on LAN, you can directly connect to the API gateway’s HTTP port 8000 via IP:Port.

An internally resolved static domain is possible. For production, a real domain and HTTPS are recommended. Use a server with a public IP and a domain that you own. Point the domain to the public IP through your cloud, DNS, or CDN provider. Local /etc/hosts resolution is an optional fallback.

The simple approach is to batch-replace the placeholder domain (supa.pigsty) with your actual domain, e.g., supa.pigsty.io:

sed -ie 's/supa.pigsty/supa.pigsty.io/g' ~/pigsty/pigsty.yml

If not configured beforehand, reload Nginx and Supabase configuration:

make cert       # Request certbot free HTTPS certificate
./app.yml -l supabase -t app_config,app_launch  # Reload Supabase configuration

The modified configuration should look like:

all:
  vars:
    certbot_sign: true                # Use certbot to sign real certificates
    infra_portal:
      home: { domain: i.pigsty.io }   # Replace with your domain!
      supa:
        domain: supa.pigsty.io        # Replace with your domain!
        endpoint: "10.10.10.10:8000"
        websocket: true
        certbot: supa.pigsty.io       # Certificate name, usually same as domain

  children:
    supabase:
      vars:
        apps:
          supabase:                                         # Supabase app definition
            conf:                                           # Override /opt/supabase/.env
              SITE_URL: https://supa.pigsty.io              # <------- Change to your external domain name
              API_EXTERNAL_URL: https://supa.pigsty.io/auth/v1 # <--- Auth external URL; keep /auth/v1
              SUPABASE_PUBLIC_URL: https://supa.pigsty.io   # <------- Don't forget to set this in infra_portal!

For complete domain/HTTPS configuration, see Certificate Management. You can also use Pigsty’s built-in local static resolution and self-signed HTTPS certificates as fallback.

Advanced: External Object Storage

You can use S3 or S3-compatible services for PostgreSQL backups and Supabase object storage. Here we use Alibaba Cloud OSS as an example.

Pigsty provides a terraform/spec/aliyun-s3.tf template for provisioning a server and OSS bucket on Alibaba Cloud.

First, modify the S3 configuration in all.children.supabase.vars.apps.supabase.conf to point to Alibaba Cloud OSS:

# if using s3/minio as file storage
S3_BUCKET: pigsty-supa                     # Legacy compatibility; keep aligned with GLOBAL_S3_BUCKET
GLOBAL_S3_BUCKET: pigsty-supa              # Bucket actually used by Supabase Storage
S3_ENDPOINT: https://oss-cn-beijing.aliyuncs.com
S3_ACCESS_KEY: <your_access_key>
S3_SECRET_KEY: <your_secret_key>
S3_FORCE_PATH_STYLE: false                 # Alibaba Cloud OSS uses host-style URIs
S3_PROTOCOL: https
S3_REGION: oss-cn-beijing                  # Legacy compatibility; keep aligned with REGION
REGION: oss-cn-beijing                     # Region actually used by Supabase Storage
STORAGE_TENANT_ID: pigsty                  # Supabase Storage tenant id
S3_PROTOCOL_ACCESS_KEY_ID: <independent_access_key>
S3_PROTOCOL_ACCESS_KEY_SECRET: <independent_secret_key>

Reload Supabase configuration:

./app.yml -l supabase -t app_config,app_launch

You can also use S3 as PostgreSQL backup repository. Add an aliyun backup repository definition in all.vars.pgbackrest_repo:

all:
  vars:
    pgbackrest_method: aliyun          # pgbackrest backup method: local,minio,[user-defined repos...]
    pgbackrest_repo:                   # pgbackrest backup repo: https://pgbackrest.org/configuration.html#section-repository
      aliyun:                          # Define new backup repo 'aliyun'
        type: s3                       # Alibaba Cloud OSS is S3-compatible
        s3_endpoint: oss-cn-beijing-internal.aliyuncs.com
        s3_region: oss-cn-beijing
        s3_bucket: pigsty-oss
        s3_key: xxxxxxxxxxxxxx
        s3_key_secret: xxxxxxxx
        s3_uri_style: host
        path: /pgbackrest
        bundle: y                         # bundle small files into a single file
        bundle_limit: 20MiB               # Limit for file bundles, 20MiB for object storage
        bundle_size: 128MiB               # Target size for file bundles, 128MiB for object storage
        cipher_type: aes-256-cbc          # enable AES encryption for remote backup repo
        cipher_pass: pgBackRest.MyPass    # Set encryption password for pgBackRest backup repo
        retention_full_type: time         # retention full backup by time on minio repo
        retention_full: 14                # keep full backup for the last 14 days

Select aliyun with all.vars.pgbackrest_method. Check the current backup and run check mode first. After explicit authorization, regenerate pgBackRest configuration on the named cluster, initialize the stanza, and create a new full recovery point:

pig pb info
./pgsql.yml -t pg_backup -l pg-meta
pg-backup full

The new repository does not automatically receive old backups. A recovery-window gap remains until its first full backup succeeds. See Switching Repositories for the complete procedure.

Advanced: Using SMTP

You can use SMTP for sending emails. Modify the supabase app configuration with SMTP information:

all:
  children:
    supabase:        # supa group
      vars:          # supa group vars
        apps:        # supa group app list
          supabase:  # the supabase app
            conf:    # the supabase app conf entries
              SMTP_HOST: smtpdm.aliyun.com
              SMTP_PORT: 80
              SMTP_USER: [email protected]
              SMTP_PASS: your_email_user_password
              SMTP_SENDER_NAME: MySupabase
              SMTP_ADMIN_EMAIL: [email protected]
              ENABLE_ANONYMOUS_USERS: false

Reload the configuration with ./app.yml -l supabase -t app_config,app_launch.

Advanced: True High Availability

These steps provide a single-node Supabase setup with a public domain, HTTPS, SMTP, PITR backups, monitoring, and IaC. It can use 600 PostgreSQL extensions. See other Pigsty documentation for high availability. Hands-on Supabase self-hosting consulting is available for $400 USD.

Single-node RTO/RPO depends on external object storage for recovery. After node failure, redeploy Supabase on a new node and restore from external S3 backups. This provides an hour-scale recovery fallback. RPO depends on actual backups and WAL archives and must be verified with restore drills. “MB-level” is not a fixed guarantee.

For RTO below 30 seconds with acknowledged transactions preserved, use multiple nodes. Explicitly select the fast RTO preset and crit.yml strict-synchronous policy. Validate them with failure drills. The default norm preset targets RTO below 45 seconds. Asynchronous replication does not promise RPO=0:

• ETCD: DCS needs three or more nodes to tolerate one node failure.
• PGSQL: PostgreSQL synchronous commit (no data loss) mode recommends at least three nodes.
• INFRA: Monitoring infrastructure failure has less impact; production recommends dual replicas.
• Supabase stateless containers can also be multi-node replicas for high availability.

In this case, you also need to modify PostgreSQL and Silo endpoints to use DNS / L2 VIP / HAProxy high availability endpoints. For these parts, follow the documentation for each Pigsty module. Reference conf/ha/trio.yml and conf/ha/safe.yml for upgrading to three or more nodes.

2 - Odoo: Self-Hosted Open Source ERP

Odoo is open-source ERP software with CRM, sales, inventory, and other business applications. The template stays on Odoo Community 19.0 for addon compatibility and uses PostgreSQL 18.

Odoo 19 requires PostgreSQL 13 or later and Python 3.10 or later; the official Docker image provides Python.

Quick Start

On a fresh Linux x86_64 / ARM64 server running a compatible operating system:

curl -fsSL https://repo.pigsty.io/get | bash; cd ~/pigsty
./bootstrap                # Install Ansible
./configure -c app/odoo    # Generate the Odoo configuration
vi pigsty.yml              # Change default passwords
./deploy.yml               # Install Pigsty and PostgreSQL
./docker.yml               # Install Docker Compose
./app.yml                  # Initialize the Odoo database and start the web container

Port 8069 is published on all host interfaces by default. Open http://<ip>:8069. The initial application login is admin / admin; change the password at first login.

The template pre-creates the odoo database and disables the database manager. ODOO_ADMIN_PASSWORD is the database-management master password, separate from the application login password.

Configuration Template

Source: conf/app/odoo.yml.

all:
  children:

    # the odoo application (default username & password: admin/admin)
    odoo:
      hosts: { 10.10.10.10: {} }
      vars:
        app: odoo   # specify app name to be installed (in the apps)
        apps:       # define all applications
          odoo:     # app name, should have corresponding ~/pigsty/app/odoo folder
            file:   # optional directory to be created
              - { path: /data/odoo         ,state: directory, owner: 100, group: 101 }
              - { path: /data/odoo/webdata ,state: directory, owner: 100, group: 101 }
              - { path: /data/odoo/addons  ,state: directory, owner: 100, group: 101 }
            conf:   # override /opt/<app>/.env config file
              PG_HOST: 10.10.10.10            # postgres host
              PG_PORT: 5432                   # postgres port
              PG_USERNAME: odoo               # postgres user
              PG_PASSWORD: DBUser.Odoo        # postgres password
              ODOO_PORT: 8069                 # published HTTP port on all host interfaces
              ODOO_PROXY_MODE: true           # trust this node's Nginx forwarded headers
              ODOO_DATA: /data/odoo/webdata    # filestore and sessions
              ODOO_ADDONS: /data/odoo/addons   # Odoo 19 addons
              ODOO_DBNAME: odoo               # odoo database name
              ODOO_ADMIN_PASSWORD: change-this-master-password # CHANGE ME: database manager master password
              ODOO_VERSION: "19.0"            # stay on Odoo 19 for addon compatibility

    # the odoo database
    pg-odoo:
      hosts: { 10.10.10.10: { pg_seq: 1, pg_role: primary } }
      vars:
        pg_cluster: pg-odoo
        pg_users:
          - { name: odoo    ,password: DBUser.Odoo ,pgbouncer: true ,roles: [ dbrole_admin ] ,comment: admin user for odoo service }
          - { name: odoo_ro ,password: DBUser.Odoo ,pgbouncer: true ,roles: [ dbrole_readonly ]  ,comment: read only user for odoo service  }
          - { name: odoo_rw ,password: DBUser.Odoo ,pgbouncer: true ,roles: [ dbrole_readwrite ] ,comment: read write user for odoo service }
        pg_databases:
          - { name: odoo ,owner: odoo ,revokeconn: true ,extensions: [unaccent, pg_trgm] ,comment: odoo main database }
        pg_hba_rules:
          - { user: odoo ,db: odoo ,addr: 172.16.0.0/12 ,auth: pwd ,title: 'allow odoo access from local docker networks' }
          - { user: dbuser_view , db: all ,addr: infra ,auth: pwd ,title: 'allow grafana dashboard access cmdb from infra nodes' }
        pg_crontab: [ '00 01 * * * /pg/bin/pg-backup full' ] # make a full backup every 1am

    infra: { hosts: { 10.10.10.10: { infra_seq: 1 } } }
    etcd:  { hosts: { 10.10.10.10: { etcd_seq: 1 } }, vars: { etcd_cluster: etcd } }
    #minio: { hosts: { 10.10.10.10: { minio_seq: 1 } }, vars: { minio_cluster: minio } }

  vars:                               # global variables
    version: v4.5.0                   # pigsty version string
    admin_ip: 10.10.10.10             # admin node ip address
    region: default                   # upstream mirror region: default|china|europe
    node_tune: oltp                   # node tuning specs: oltp,olap,tiny,crit
    pg_conf: oltp.yml                 # pgsql tuning specs: {oltp,olap,tiny,crit}.yml

    docker_enabled: true              # enable docker on app group
    #docker_registry_mirrors: ["https://docker.1panel.live","https://docker.1ms.run","https://docker.xuanyuan.me","https://registry-1.docker.io"]

    proxy_env:                        # global proxy env when downloading packages & pull docker images
      no_proxy: "localhost,127.0.0.1,10.0.0.0/8,192.168.0.0/16,*.pigsty,*.aliyun.com,mirrors.*,*.tsinghua.edu.cn"
      #http_proxy:  127.0.0.1:12345 # add your proxy env here for downloading packages or pull images
      #https_proxy: 127.0.0.1:12345 # usually the proxy is format as http://user:[email protected]
      #all_proxy:   127.0.0.1:12345

    infra_portal:                     # domain names and upstream servers
      home  : { domain: i.pigsty }
      minio : { domain: m.pigsty ,endpoint: "${admin_ip}:9001" ,scheme: https ,websocket: true }
      odoo:                           # nginx server config for odoo
        domain: odoo.pigsty           # REPLACE WITH YOUR OWN DOMAIN!
        endpoint: "10.10.10.10:8069"  # Odoo host IP and published HTTP port
        websocket: true               # HTTP and WebSocket share 8069 with the default workers=0
        certbot: odoo.pigsty          # cert name; use your real domain for public certificates

    repo_enabled: false
    node_repo_modules: node,infra,pgsql
    pg_version: 18                    # Odoo 19 requires PostgreSQL 13 or later

    #----------------------------------------------#
    # PASSWORD : https://pigsty.io/docs/setup/security/
    #----------------------------------------------#
    grafana_admin_password: pigsty
    grafana_view_password: DBUser.Viewer
    pg_admin_password: DBUser.DBA
    pg_monitor_password: DBUser.Monitor
    pg_replication_password: DBUser.Replicator
    patroni_password: Patroni.API
    haproxy_admin_password: pigsty
    minio_secret_key: S3User.MinIO
    etcd_root_password: Etcd.Root

Basics

The deployed configuration is in /opt/odoo/.env:

PG_HOST=10.10.10.10
PG_PORT=5432
PG_USERNAME=odoo
ODOO_DBNAME=odoo
PG_PASSWORD=DBUser.Odoo
ODOO_PORT=8069
ODOO_PROXY_MODE=true
ODOO_DATA=/data/odoo/webdata
ODOO_ADDONS=/data/odoo/addons
ODOO_ADMIN_PASSWORD=change-this-master-password
ODOO_VERSION=19.0

ODOO_PORT is the published host port number. Compose maps it to the fixed container port 8069 with "${ODOO_PORT}:8069". ODOO_DBNAME selects one database; its name must not contain commas.

For manual deployment, create the PostgreSQL role, database, and extensions first, then run these commands on the Docker host. The Make helpers require Docker Compose, jq, and permission to set directory ownership.

cd /opt/odoo
make init  # Initialize the existing empty database
make up    # Start the web service

Makefile

make            # Initialize, start the service, and print its access point
make init       # Prepare directories and initialize the existing empty database
make up         # Start or recreate the web container
make view       # Print the access point
make logs       # Follow container logs
make info       # Inspect the container
make stop       # Stop containers
make down       # Remove Compose containers and networks
make pull       # Pull the image selected by ODOO_VERSION
make restart    # Restart existing containers
make port       # Show the published port
make save       # Save the image to /tmp/docker/odoo.tgz
make load       # Load the image from /tmp/docker/odoo.tgz

Using External PostgreSQL

PostgreSQL 13 or later is supported. Create a dedicated role, database, and the unaccent / pg_trgm extensions:

pg_users: [ { name: odoo ,password: DBUser.Odoo ,roles: [ dbrole_admin ] ,comment: admin user for odoo service } ]
pg_databases: [ { name: odoo ,owner: odoo ,revokeconn: true ,extensions: [unaccent, pg_trgm] ,comment: odoo main database } ]

Replace pg-meta below with the actual database cluster name:

bin/pgsql-user  pg-meta  odoo
bin/pgsql-db    pg-meta  odoo

Point PG_HOST, PG_PORT, PG_USERNAME, and PG_PASSWORD in .env to that database, and configure HBA to allow the application. This single-database template does not require CREATEDB or SUPERUSER for the Odoo role.

Check connectivity, entering the password at the prompt:

psql -h 10.10.10.10 -p 5432 -U odoo -d odoo -W -c 'SELECT version();'

Expose Odoo Service

You can also access Odoo through the Nginx portal. Use ODOO_PROXY_MODE=true for proxy access and false for direct access only. Run make up after changing .env.

infra_portal:
  odoo:
    domain: odoo.pigsty
    endpoint: "10.10.10.10:8069"
    websocket: true
    certbot: odoo.pigsty  # Use a real domain for public certificates

Point domain to the Nginx host and endpoint to the Odoo host and published port. Update this port if you change ODOO_PORT.

./infra.yml -t nginx   # Update the Nginx portal configuration

With the default workers=0, HTTP and WebSocket share port 8069. Multiple workers require separate port 8072 and /websocket routing; see the Odoo 19 deployment guide.

Use HTTPS in production. Trust Pigsty’s files/pki/ca/ca.crt on the client or configure a publicly trusted certificate.

Odoo Addons

Use addons compatible with Odoo 19. Extract them into /data/odoo/addons (mounted at /mnt/extra-addons in the container) and install their dependencies. Set directory ownership to uid=100, gid=101.

Run make restart after changing addon code. Enable Developer mode, then refresh and install addons in Apps → Update Apps List. Find more addons in Odoo Apps.

Updates and Backups

To update the Odoo 19 image, run make pull, then make up. make restart does not apply a new image or environment. For a fixed version, set ODOO_VERSION to a published dated 19.0 tag. A major-version upgrade requires database migration and compatible addons.

Use Pigsty/pgBackRest for database backups. Manage filestore and addon backups yourself with Restic or PGFS.

Demo

Public demo (availability varies): http://odoo.pigsty.io, username [email protected], password pigsty.

3 - Dify: AI Workflow Platform

Dify is an open-source platform for developing generative AI and LLM applications. It supports agent creation, AI workflows, RAG retrieval, and model management. These features help users build and operate generative AI applications.

Pigsty supports self-hosted Dify with single-command deployment. Critical state resides in externally managed PostgreSQL. You can use pgvector in the same PostgreSQL instance as the vector database to simplify deployment.

• Quick Start
• Why Self-Host
• Installation
• Configuration
• Checklist
• Domain and SSL
• Upgrading
• File Backup

The template uses Dify v1.17.1 with plugin daemon v0.6.10-local and sandbox v0.2.15. Validation on 2026-10-08 covered login, an existing Code workflow, and service connections on Linux amd64 with PostgreSQL 18.6. Dify v1.16 and later handle PostgreSQL 18’s built-in uuidv7() without a local migration patch.

Quick Start

On a fresh Linux x86/ARM server running a compatible operating system:

curl -fsSL https://repo.pigsty.io/get | bash; cd ~/pigsty
./bootstrap                # Install Pigsty dependencies
./configure -c app/dify    # Use Dify configuration template
vi pigsty.yml              # Edit passwords, domains, keys, etc.

./deploy.yml               # Install Pigsty
./docker.yml               # Install Docker and Compose
./app.yml                  # Install Dify

Dify listens on port 5001 by default. Access http://<ip>:5001 in your browser and set up your initial user credentials to log in.

After Dify starts, install extensions and configure system models to begin using it.

Why Self-Host

Data security is a primary reason to self-host Dify. Dify’s Docker Compose template uses basic database images. It lacks enterprise features such as high availability, disaster recovery, monitoring, IaC, and PITR.

Pigsty provides declarative Dify deployment and image mirrors for access in China. The template places PostgreSQL and pgvector under Pigsty management. It deploys Compose Redis, VictoriaMetrics/Grafana monitoring, and an Nginx reverse proxy. After public DNS, ports, and Certbot are configured, it can request a Let’s Encrypt certificate. Files use DIFY_DATA (/data/dify) by default, with optional Silo/S3 object storage.

The template places PostgreSQL/pgvector in an externally managed Pigsty database. API files and plugin data use DIFY_DATA, which defaults to /data/dify. Compose Redis data remains in /opt/dify/volumes/redis/data. Sandbox dependencies and Certbot data also use /opt/dify/volumes/. The Agent local sandbox also stores /home/dify and /workspace in separate named volumes. Backups must include these volumes as well as the database and host directories.

Installation

Start with a single-node Dify deployment. Production high-availability deployment is covered later.

First, use Pigsty’s standard installation process to install the PostgreSQL instance required by Dify:

curl -fsSL https://repo.pigsty.io/get | bash; cd ~/pigsty
./bootstrap               # Prepare Pigsty dependencies
./configure -c app/dify   # Use Dify application template
vi pigsty.yml             # Edit configuration file, modify domains and passwords
./deploy.yml              # Install Pigsty and various databases

The ./configure -c app/dify command generates configuration from conf/app/dify.yml and your current environment. Edit passwords, domains, and other required settings in pigsty.yml. Then run ./deploy.yml to perform the standard installation.

Next, run docker.yml to install Docker and Docker Compose, then use app.yml to complete Dify deployment:

./docker.yml -l dify      # Install Docker and Docker Compose on Dify nodes
./app.yml -l dify         # Deploy Dify application components with Docker

You can access the Dify Web admin interface at http://<your_ip_address>:5001 on your local network.

The first login will prompt you to set up default username, email, and password.

You can also use the locally resolved placeholder domain dify.pigsty, or follow the configuration below to use a real domain with an HTTPS certificate.

Configuration

When you run ./configure -c app/dify, Pigsty generates a configuration file from the conf/app/dify.yml template and the current environment. The snapshot below matches the v4.5.0 source template:

---
#==============================================================#
# File      :   dify.yml
# Desc      :   pigsty config for running 1-node dify app
# Ctime     :   2025-02-24
# Mtime     :   2026-08-27
# Docs      :   https://pigsty.io/docs/app/dify
# License   :   Apache-2.0 @ https://pigsty.io/docs/about/license/
# Copyright :   2018-2026  Ruohang Feng / Vonng ([email protected])
#==============================================================#
# Last Verified Dify Version: v1.17.0 on 2026-08-27 (Pigsty PG18, arm64)
# tutorial: https://pigsty.io/docs/app/dify
# how to use this template:
#
#  curl -fsSL https://repo.pigsty.io/get | bash; cd ~/pigsty
# ./bootstrap               # prepare local repo & ansible
# ./configure -c app/dify   # use this dify config template
# vi pigsty.yml             # IMPORTANT: CHANGE CREDENTIALS!!
# ./deploy.yml              # install pigsty & pgsql
# ./docker.yml              # install docker & docker-compose
# ./app.yml                 # install dify with docker-compose
#
# To replace domain name:
#   sed -ie 's/dify.pigsty/dify.pigsty.cc/g' pigsty.yml


all:
  children:

    # the dify application
    dify:
      hosts: { 10.10.10.10: {} }
      vars:
        app: dify   # specify app name to be installed (in the apps)
        apps:       # define all applications
          dify:     # app name, should have corresponding ~/pigsty/app/dify folder
            file:   # data directory to be created
              - { path: /data/dify ,state: directory ,mode: 0755 }
            conf:   # override /opt/dify/.env config file

              # change domain, mirror, proxy, secret key
              NGINX_SERVER_NAME: dify.pigsty
              # A secret key for signing and encryption, gen with `openssl rand -base64 42` (CHANGE PASSWORD!)
              SECRET_KEY: sk-somerandomkey
              # Dify Agent secrets (CHANGE ALL THREE; generate independent random values)
              DIFY_AGENT_API_TOKEN: change-this-agent-api-token
              # Valid 32-byte development key encoded as base64url; CHANGE ME.
              DIFY_AGENT_SERVER_SECRET_KEY: MDEyMzQ1Njc4OWFiY2RlZjAxMjM0NTY3ODlhYmNkZWY
              DIFY_AGENT_LOCAL_SANDBOX_AUTH_TOKEN: change-this-local-sandbox-auth-token
              # expose DIFY nginx service with port 5001 by default
              DIFY_PORT: 5001
              # where to store dify files? the default is ./volume, we'll use another volume created above
              DIFY_DATA: /data/dify
              # enable the upstream websocket sidecar, while keeping PostgreSQL/pgvector external
              COMPOSE_PROFILES: collaboration
              NEXT_PUBLIC_SOCKET_URL: ws://dify.pigsty
              TRIGGER_URL: http://dify.pigsty
              ENDPOINT_URL_TEMPLATE: http://dify.pigsty/e/{hook_id}

              # proxy and mirror settings
              #PIP_MIRROR_URL: https://pypi.tuna.tsinghua.edu.cn/simple
              #SANDBOX_HTTP_PROXY: http://10.10.10.10:12345
              #SANDBOX_HTTPS_PROXY: http://10.10.10.10:12345

              # database credentials
              DB_TYPE: postgresql
              DB_USERNAME: dify
              DB_PASSWORD: difyai123456
              DB_HOST: 10.10.10.10
              DB_PORT: 5432
              DB_DATABASE: dify
              DB_SSL_MODE: disable
              VECTOR_STORE: pgvector
              PGVECTOR_HOST: 10.10.10.10
              PGVECTOR_PORT: 5432
              PGVECTOR_USER: dify
              PGVECTOR_PASSWORD: difyai123456
              PGVECTOR_DATABASE: dify
              PGVECTOR_MIN_CONNECTION: 2
              PGVECTOR_MAX_CONNECTION: 10

              # optional Silo/S3 storage, disabled by default to avoid touching the backup repository
              #STORAGE_TYPE: s3
              #S3_ENDPOINT: http://10.10.10.10:9000
              #S3_BUCKET_NAME: dify
              #S3_ACCESS_KEY: dify
              #S3_SECRET_KEY: S3User.Dify
              #S3_REGION: us-east-1
              #S3_ADDRESS_STYLE: path

    pg-meta:
      hosts: { 10.10.10.10: { pg_seq: 1, pg_role: primary } }
      vars:
        pg_cluster: pg-meta
        pg_extensions: [ pgvector ]
        pg_users:
          - { name: dify ,password: difyai123456 ,pgbouncer: true ,roles: [ dbrole_admin ] ,superuser: true ,comment: dify superuser }
        pg_databases:
          - { name: dify        ,owner: dify ,extensions: [ { name: vector } ] ,comment: dify main database  }
          - { name: dify_plugin ,owner: dify ,comment: dify plugin daemon database }
        pg_hba_rules:
          - { user: dify ,db: all ,addr: 172.16.0.0/12  ,auth: pwd ,title: 'allow dify access from local docker networks' }
        pg_crontab: [ '00 01 * * * /pg/bin/pg-backup full' ] # make a full backup every 1am

    infra: { hosts: { 10.10.10.10: { infra_seq: 1 } } }
    etcd:  { hosts: { 10.10.10.10: { etcd_seq: 1 } }, vars: { etcd_cluster: etcd } }
    #minio: { hosts: { 10.10.10.10: { minio_seq: 1 } }, vars: { minio_cluster: minio } }

  vars:                               # global variables
    version: v4.5.0                   # pigsty version string
    admin_ip: 10.10.10.10             # admin node ip address
    region: default                   # upstream mirror region: default|china|europe
    node_tune: oltp                   # node tuning specs: oltp,olap,tiny,crit
    pg_conf: oltp.yml                 # pgsql tuning specs: {oltp,olap,tiny,crit}.yml

    docker_enabled: true              # enable docker on app group
    #docker_registry_mirrors: ["https://docker.1panel.live","https://docker.1ms.run","https://docker.xuanyuan.me","https://registry-1.docker.io"]

    proxy_env:                        # global proxy env when downloading packages & pull docker images
      no_proxy: "localhost,127.0.0.1,10.0.0.0/8,192.168.0.0/16,*.pigsty,*.aliyun.com,mirrors.*,*.tsinghua.edu.cn"
      #http_proxy:  127.0.0.1:12345 # add your proxy env here for downloading packages or pull images
      #https_proxy: 127.0.0.1:12345 # usually the proxy is format as http://user:[email protected]
      #all_proxy:   127.0.0.1:12345

    infra_portal:                     # domain names and upstream servers
      home   :  { domain: i.pigsty }
      #minio :  { domain: m.pigsty    ,endpoint: "${admin_ip}:9001" ,scheme: https ,websocket: true }
      dify:                            # nginx server config for dify
        domain: dify.pigsty            # REPLACE WITH YOUR OWN DOMAIN!
        endpoint: "10.10.10.10:5001"   # dify service endpoint: IP:PORT
        websocket: true                # add websocket support
        certbot: dify.pigsty           # certbot cert name, apply with `make cert`

    repo_enabled: false
    node_repo_modules: node,infra,pgsql
    # Dify v1.16+ natively handles PostgreSQL 18's built-in uuidv7().
    pg_version: 18

    #----------------------------------------------#
    # PASSWORD : https://pigsty.io/docs/setup/security/
    #----------------------------------------------#
    grafana_admin_password: pigsty
    grafana_view_password: DBUser.Viewer
    pg_admin_password: DBUser.DBA
    pg_monitor_password: DBUser.Monitor
    pg_replication_password: DBUser.Replicator
    patroni_password: Patroni.API
    haproxy_admin_password: pigsty
    minio_secret_key: S3User.MinIO
    etcd_root_password: Etcd.Root
...

Checklist

Check these configuration items:

• Hardware/Software: Prepare required machine resources: Linux x86_64/arm64 server, fresh installation of a mainstream Linux OS
• Network/Permissions: SSH passwordless login access, user with sudo privileges without password
• Ensure the machine has a static IPv4 network address on the internal network and can access the internet
• If accessing via public network, ensure you have a domain pointing to the node’s public IP address
• Ensure you use the app/dify configuration template and modify parameters as needed
  • configure -c app/dify, enter the node’s internal primary IP address, or specify via -i <primary_ip> command line parameter
• In production, change every example password, application secret, and database credential. [Required]
  • grafana_admin_password: pigsty, Grafana admin password
  • pg_admin_password: DBUser.DBA, PG superuser password
  • pg_monitor_password: DBUser.Monitor, PG monitoring user password
  • pg_replication_password: DBUser.Replicator, PG replication user password
  • patroni_password: Patroni.API, Patroni HA component password
  • haproxy_admin_password: pigsty, Load balancer admin password
• Change the PostgreSQL business user password and the application settings that use it.
  • Default username dify and password difyai123456 are generated by Pigsty for Dify; modify according to your needs
  • In the Dify configuration block, modify DB_USERNAME, DB_PASSWORD, PGVECTOR_USER, PGVECTOR_PASSWORD accordingly
• Change Dify’s default encryption key.
  • You can randomly generate a password string with openssl rand -base64 42 and fill in the SECRET_KEY parameter
  • Also replace the three Agent development secrets: DIFY_AGENT_API_TOKEN, DIFY_AGENT_SERVER_SECRET_KEY, and DIFY_AGENT_LOCAL_SANDBOX_AUTH_TOKEN. Generate independent random values; use the format produced by secrets.token_urlsafe(32) for the server secret.
• Change the domain used by Dify.
  • Replace placeholder domain dify.pigsty with your actual domain, e.g., dify.pigsty.io
  • You can use sed -ie 's/dify.pigsty/dify.pigsty.io/g' pigsty.yml to modify Dify’s domain

Domain and SSL

To use a real domain with HTTPS, update these settings in pigsty.yml:

• The dify domain in the infra_portal parameter
• It’s best to specify an email address certbot_email for certificate expiration notifications
• Configure Dify’s NGINX_SERVER_NAME parameter to specify your actual domain

all:
  children:                            # Cluster definitions
    dify:                              # Dify group
      vars:                            # Dify group variables
        apps:                          # Application configuration
          dify:                        # Dify application definition
            conf:                      # Dify application configuration
              NGINX_SERVER_NAME: dify.pigsty

  vars:                                # Global parameters
    #certbot_sign: true                # Use Certbot for free HTTPS certificate
    certbot_email: [email protected]      # Email for certificate requests, for expiration notifications, optional
    infra_portal:                      # Configure Nginx servers
      dify:                            # Dify server definition
        domain: dify.pigsty            # Replace with your own domain here!
        endpoint: "10.10.10.10:5001"   # Specify Dify's IP and port here (auto-configured by default)
        websocket: true                # Dify requires websocket enabled
        certbot: dify.pigsty           # Specify Certbot certificate name

Use the following commands to request Nginx certificates:

# Request and load the certificate on the explicitly limited infra group
./infra.yml -l infra -t nginx_certbot,nginx_reload -e certbot_sign=true

Run the app.yml playbook to redeploy Dify service for the NGINX_SERVER_NAME configuration to take effect:

./app.yml -l dify -t app_config,app_launch

Upgrading

Before upgrading, verify the PostgreSQL backup and back up the files and named volumes listed below. With MIGRATION_ENABLED=true, the API container runs database migrations at startup. After updating configuration, pulling the new images, and recreating the API container, confirm that it runs the new version before invoking migrations explicitly:

docker compose exec api flask db upgrade

Dify 1.17.1 includes the pre-1.15 legacy model type migration in this process. The separate flask data-migrate legacy-model-types command is no longer needed. Deployments upgrading from before 1.15 that have not completed the plugin auto-upgrade backfill must still run it once:

docker compose exec api flask backfill-plugin-auto-upgrade

When upgrading from 1.16, rename EDITION to DEPLOYMENT_EDITION, DIFY_AGENT_SHELLCTL_AUTH_TOKEN to DIFY_AGENT_LOCAL_SANDBOX_AUTH_TOKEN, DIFY_AGENT_SHELLCTL_ENTRYPOINT to DIFY_AGENT_LOCAL_SANDBOX_ENDPOINT, and AGENT_BACKEND_RUN_TIMEOUT_SECONDS to DIFY_AGENT_RUN_TIMEOUT_SECONDS in deployment overrides. Use DIFY_AGENT_RUNTIME_BACKEND=local for the bundled self-hosted sandbox.

Version 1.17.1 fixes document extraction, Human Input workflows, collaboration, and Agent behavior. Re-import CSV, Notion, and XLS documents that were previously extracted incorrectly; replacing the image does not repair indexed text. See the 1.17.1 release notes.

The Agent feature remains Beta and should be exposed only to trusted users. SSRF_PROXY_ALLOW_PRIVATE_IPS and SSRF_PROXY_ALLOW_PRIVATE_DOMAINS apply to both workflow and Agent proxies. Leave them empty for the default private-network deny policy. Explicitly allowlisting api, agent_backend, or a network covering their addresses also allows their other ordinary paths; use precise targets. The Agent shellctl control network still permits direct access from the local sandbox to agent_backend.

File Backup

Use restic to back up Dify file state. Include at least /data/dify, /opt/dify/.env, and /opt/dify/volumes/. The last directory contains Compose Redis, Sandbox dependencies, and any Certbot data. Back up PostgreSQL separately with Pigsty/pgBackRest. Also back up the dify_agent_local_sandbox_home and dify_agent_local_sandbox_workspace named volumes, whose actual names include the Compose project prefix. The Restic commands below do not include these two volumes.

export RESTIC_REPOSITORY=/data/backups/dify   # Specify dify backup directory
export RESTIC_PASSWORD=some-strong-password   # Specify backup encryption password
mkdir -p ${RESTIC_REPOSITORY}                 # Create dify backup directory
restic init

After creating the Restic backup repository, you can backup Dify with:

export RESTIC_REPOSITORY=/data/backups/dify   # Specify dify backup directory
export RESTIC_PASSWORD=some-strong-password   # Specify backup encryption password

restic backup /data/dify /opt/dify/.env /opt/dify/volumes
restic snapshots                              # View backup snapshot list
restic restore 0b11f778 --target /tmp/dify-restore  # Restore to a temporary directory first, verify, then copy back
restic check                                  # Periodically check repository integrity

Another option is to place /data/dify on a shared filesystem managed by the JUICE module. File data can live in Silo/S3 or in a PostgreSQL jfs_blob table; the latter is not PostgreSQL large-object storage.

To store JuiceFS metadata and file data in PostgreSQL, declare a dedicated database and least-privilege user in pg_databases. Then declare the instance on the Dify node. The example passwords are placeholders. Do not use them in production.

pg_databases:
  - { name: dify_fs, owner: dify, comment: JuiceFS metadata and data for Dify }

juice_instances:
  dify:
    path: /data/dify
    meta: postgres://dify:<password>@10.10.10.10:5432/dify_fs
    data: --storage postgres --bucket 10.10.10.10:5432/dify_fs --access-key dify --secret-key <password>
    owner: 1001
    group: 1001
    port: 9567

Handle database creation and JUICE deployment separately. After confirming the exact targets, run the playbooks:

./pgsql-db.yml -l pg-meta -e dbname=dify_fs
./juice.yml -l dify -e fsname=dify

Database creation, initial filesystem formatting, and mounting change the target environment. Confirm the backup, database name, and host group before execution. Start Dify only after the mount is ready. See JUICE configuration and its PITR consistency boundary. Before mounting over a nonempty /data/dify, stop Dify and plan migration of existing files.

Reference

Dify Self-Hosting FAQ

4 - InsForge: AI Backend-as-a-Service

InsForge is an open-source Backend-as-a-Service platform for AI coding agents, built around PostgreSQL. It provides authentication, database APIs, file storage, a model gateway, edge functions, site deployment, and payment integrations. These features reduce common backend implementation work.

Pigsty provides the app/insforge template. It runs stateless InsForge OSS services in Docker Compose and stores critical state in Pigsty-managed PostgreSQL. This provides high availability, backup and recovery, monitoring, ingress domains, and infrastructure services. The database does not depend on an ephemeral container volume.

The template targets InsForge OSS v2.3.3 and uses external PostgreSQL. It runs three services by default: InsForge Dashboard/API, PostgREST, and Deno Runtime. The latter two bind only to host loopback.

Quick Start

Run the following on a fresh Linux x86 / ARM server with a compatible operating system:

curl -fsSL https://repo.pigsty.io/get | bash; cd ~/pigsty
./bootstrap                  # Install Pigsty dependencies
./configure -c app/insforge  # Use the InsForge configuration template
vi pigsty.yml                # Required: keys, admin account, database password, domain

./infra.yml                  # Create the CA and initialize infrastructure first
./node.yml -l pg-meta         # Provision PostgreSQL nodes
./pgsql.yml -l pg-meta -t pg_install # Install PostgreSQL packages only
# Install the utility library on every PostgreSQL node; Debian/Ubuntu PG18 example
sudo apt-get install -y postgresql-server-dev-18 build-essential curl patch
sudo env PG_CONFIG=/usr/lib/postgresql/18/bin/pg_config bash app/insforge/pgutils/install.sh
./deploy.yml                 # Initialize PostgreSQL with the library preloaded and deploy Pigsty
./docker.yml                 # Install Docker and Compose
./app.yml                    # Install InsForge

On a fresh deployment, run infra.yml first so node.yml can use its CA. Existing Pigsty deployments should retain their INFRA/ETCD inventory and avoid repeating initialization. See Database and Permissions for the utility library requirements on every database node.

After installation, the default access URLs are:

• http://<your_ip_address>:7130
• http://isf.pigsty

The default administrator account is [email protected] / pigsty. In production, you must change the administrator account, administrator password, JWT secret, encryption key, and database password.

To access InsForge through isf.pigsty, add the following entry to /etc/hosts on the machine running your browser:

10.10.10.10 isf.pigsty

To expose the service to the public internet, use a real domain and HTTPS certificate, and modify infra_portal as described below.

Checklist

• Prepare a fresh Linux server with at least 2C4G; use an SSD/NVMe disk.
• Confirm that the server has a static private IPv4 address and can access GHCR / Docker Hub, or that a registry mirror is configured.
• After running ./configure -c app/insforge, change the default passwords, domains, and keys in pigsty.yml.
• Generate new JWT_SECRET and ENCRYPTION_KEY values separately with openssl rand -base64 32.
• Keep POSTGRES_PASSWORD consistent with the password of dbuser_insforge in pg_users.
• For public access, configure a real domain, an HTTPS certificate, and firewall access rules.
• Install and preload insforge_pg_utils on every PostgreSQL node, verify the extension packages, and run pig pb info after deployment.

Architecture

The InsForge template separates the database from the application containers by default:

                    ┌──────────────────────────────────────────────┐
                    │                 InsForge Stack               │
┌──────────┐       │  ┌──────────┐  ┌──────────┐  ┌───────────┐  │
│  Nginx   │──────▶│  │ InsForge │  │PostgREST │  │   Deno    │  │
│ (Pigsty) │  :7130│  │ App+Web  │  │ REST API │  │  Runtime  │  │
└──────────┘       │  │  :7130   │  │  :5430   │  │   :7133   │  │
                    │  └────┬─────┘  └────┬─────┘  └─────┬─────┘  │
                    │       │             │              │         │
                    └───────┼─────────────┼──────────────┼─────────┘
                            │             │              │
                            ▼             ▼              ▼
                    ┌──────────────────────────────────────────────┐
                    │  PostgreSQL (Pigsty Managed HA Cluster)      │
                    │  Patroni + pgBackRest + pgBouncer + HAProxy  │
                    └──────────────────────────────────────────────┘

Components:

• InsForge App: ghcr.io/insforge/insforge-oss:v2.3.3, providing the Dashboard and main API on port 7130.
• PostgREST: postgrest/postgrest:v12.2.12, generating REST APIs from PostgreSQL schemas; bound to 127.0.0.1:5430 on the host.
• Deno Runtime: denoland/deno:alpine-2.0.6, running the bundled, pinned function host and bound to 127.0.0.1:7133 on the host.
• PostgreSQL: Managed by Pigsty for persistent state, backup, monitoring, and high availability.

Configuration Template

conf/app/insforge.yml defines a single-node, self-hosted InsForge template. The default topology includes:

• insforge: The node running the InsForge, PostgREST, and Deno Runtime containers.
• pg-meta: The PostgreSQL database cluster managed by Pigsty, including the roles, database, and extensions required by InsForge.
• infra: Infrastructure services such as Nginx ingress, Grafana, and VictoriaMetrics.
• etcd: The distributed configuration store required by Patroni.

Key configuration excerpts:

insforge:
  hosts: { 10.10.10.10: {} }
  vars:
    app: insforge
    apps:
      insforge:
        conf:
          JWT_SECRET: your-secret-key-here-must-be-32-char-or-above
          ENCRYPTION_KEY: your-encryption-key-here-must-be-32-char-or-above
          ROOT_ADMIN_USERNAME: [email protected]
          ROOT_ADMIN_PASSWORD: pigsty
          POSTGRES_HOST: 10.10.10.10
          POSTGRES_PORT: 5432
          POSTGRES_DB: insforge
          POSTGRES_USER: dbuser_insforge
          POSTGRES_PASSWORD: DBUser.Insforge

pg-meta:
  hosts: { 10.10.10.10: { pg_seq: 1, pg_role: primary } }
  vars:
    pg_cluster: pg-meta
    pg_users:
      - { name: dbuser_insforge ,password: DBUser.Insforge ,pgbouncer: true ,roles: [dbrole_admin] ,superuser: true ,comment: 'insforge superuser' }
      - { name: anon            ,login: false ,comment: 'insforge anonymous role for PostgREST' }
      - { name: authenticated   ,login: false ,comment: 'insforge authenticated role' }
      - { name: project_admin   ,login: false ,bypassrls: true ,comment: 'insforge project admin with RLS bypass' }
    pg_databases:
      - name: insforge
        owner: dbuser_insforge
        baseline: insforge.sql
        extensions: [pgcrypto, http, pg_cron]
    pg_libs: 'pg_cron, insforge_pg_utils, pg_stat_statements, auto_explain'
    pg_parameters:
      cron.database_name: insforge
      cron.use_background_workers: true
      app.encryption_key: your-encryption-key-here-must-be-32-char-or-above
      insforge.policy_grant_role: project_admin
      insforge.extension_grant_role: project_admin
      insforge.policy_grant_tables: 'storage.objects,realtime.channels,realtime.messages,payments.stripe_checkout_sessions,payments.stripe_customer_portal_sessions,payments.razorpay_orders,payments.razorpay_subscriptions'
      insforge.internal_schemas: 'ai,auth,compute,deployments,email,functions,memory,payments,realtime,schedules,storage,system'
    pg_extensions: [ pg_cron, pg_http ]
    pg_hba_rules:
      - { user: dbuser_insforge ,db: all ,addr: 172.16.0.0/12 ,auth: pwd ,title: 'allow insforge access from local docker networks' }

Important Parameters

app.yml copies the app/insforge directory to /opt/insforge and uses apps.insforge.conf to override /opt/insforge/.env. Common parameters include:

Generate production secrets with:

openssl rand -base64 32

When changing the database password, keep the application and database definitions synchronized. For example:

apps:
  insforge:
    conf:
      POSTGRES_PASSWORD: <new-password>

pg_users:
  - { name: dbuser_insforge ,password: <new-password> ,pgbouncer: true ,roles: [dbrole_admin] ,superuser: true }

Once ENCRYPTION_KEY has been used for production data, keep it stable. Changing it may make stored runtime credentials such as API keys, OAuth tokens, and function secrets impossible to decrypt.

Database and Permissions

The default InsForge database is named insforge and owned by dbuser_insforge. The template creates the following roles:

files/insforge.sql configures PostgREST role privileges, default privileges, ACLs for project_admin, and the helper function public.reload_postgrest_schema(). The function executes:

NOTIFY pgrst, 'reload schema';

This notifies PostgREST to reload its schema.

insforge_pg_utils is a required PostgreSQL utility library. It lets project_admin manage RLS policies on managed tables and manage extensions; application migrations do not replace it. Copy the complete app/insforge/pgutils/ directory to every database node, install it before PostgreSQL initialization, and preload it through pg_libs. It exposes no SQL objects, so no CREATE EXTENSION is needed.

pgutils/install.sh downloads and verifies pinned official source, applies the PG16–18 compatibility patch, and builds it with PGXS. For PG18 on Debian/Ubuntu, use postgresql-server-dev-18 and /usr/lib/postgresql/18/bin/pg_config. On EL/RPM, use postgresql18-devel, gcc, make, curl, patch, and /usr/pgsql-18/bin/pg_config. The script does not change configuration or restart a cluster; plan preload configuration and restart separately for an existing deployment.

cron.use_background_workers: true runs scheduled jobs as background workers without adding a loopback trust rule. Reserve enough max_worker_processes slots for cron, replication, and other extensions.

Service Ports and Persistence

The default Docker Compose services are:

Remote clients use the main InsForge API for data and functions; do not expose PostgREST or Deno directly. The Docker compute provider is optional, and the template does not mount the Docker socket by default. Enabling that mount grants the container root-equivalent access to the host.

The default Docker volumes are:

By default, Docker containers connect to the Pigsty node at 10.10.10.10:5432. The template HBA rule permits 172.16.0.0/12, covering Docker’s default bridge and common custom bridge networks.

Domain and Ingress

The template adds an InsForge entry to infra_portal by default:

infra_portal:
  home    : { domain: i.pigsty }
  insforge:
    domain: isf.pigsty
    endpoint: "10.10.10.10:7130"
    websocket: true
    certbot: isf.pigsty

To use a real domain such as insforge.example.com, replace the placeholder in bulk:

sed -ie 's/isf.pigsty/insforge.example.com/g' pigsty.yml

Then apply the Nginx ingress configuration:

./infra.yml -t nginx

Before requesting an HTTPS certificate, verify that the domain resolves to the current node. Then add or update certbot under infra_portal.insforge:

insforge:
  domain: insforge.example.com
  endpoint: "10.10.10.10:7130"
  websocket: true
  certbot: insforge.example.com

Then run:

make cert
./infra.yml -t nginx

Operations

InsForge is installed in /opt/insforge. Common commands include:

cd /opt/insforge

make up       # Start services
make view     # Print access URLs
make info     # Show container status
make log      # Follow logs
make restart  # Restart containers
make down     # Stop containers
make clean    # Remove stopped containers
make edit     # Edit .env

Upgrade to v2.3.3

Before upgrading, back up PostgreSQL, including system.migrations, file storage, and deployment overrides. Preserve the existing JWT and credential-encryption keys. After you pull the new image and recreate the InsForge container, its startup migration runner applies and records 065_restrict-http-extension-to-admin.

This migration revokes PUBLIC EXECUTE on 13 outbound HTTP and curl-option function signatures from the http extension while retaining project_admin execution. This prevents normal users and anonymous API keys from invoking them through RPC. The new-install files/insforge.sql baseline includes the same restriction. Do not replay the full baseline on an existing database or run a separate copy of migration 065 manually.

After upgrading, check the migration ledger and actual function privileges. The defaults should be anon=false, authenticated=false, and project_admin=true. Custom role memberships or explicit grants can still confer additional access. See the template upgrade checks and official migration.

Offline Deployment

For offline environments, save the images in advance:

cd /opt/insforge
make pull
make save
make tarball

The first Deno startup needs access to deno.land and registry.npmjs.org to pre-cache the function host and worker dependencies. The SDK is pinned to @insforge/[email protected], and functions/deno.lock fixes the dependency graph. Configure DENO_HTTP_PROXY / DENO_HTTPS_PROXY if needed. make save archives images only, not the deno_cache volume; prepare and transfer that cache separately for offline use.

Default artifact locations:

• /tmp/docker/insforge/postgrest.tgz
• /tmp/docker/insforge/insforge.tgz
• /tmp/docker/insforge/deno.tgz
• /tmp/insforge.tgz

Load the images on the target machine:

cd /opt/insforge
make load
make up

Data and Backup

InsForge state is divided into two categories:

• Business data, users, project metadata, permissions, and related state are stored in the Pigsty PostgreSQL database insforge.
• Local files and logs are stored in the Docker volumes storage-data and insforge-logs.

By default, the template schedules a full PostgreSQL backup every day at 1:00 AM:

pg_crontab: [ '00 01 * * * /pg/bin/pg-backup full' ]

After deployment, check the backup status:

pig pb info

If file storage is configured to use S3 / MinIO, file objects are managed by that object storage system. If you keep local volumes, include them separately in your host-level backup strategy.

Troubleshooting

Check container status:

cd /opt/insforge
make info

View logs:

sudo docker logs insforge
sudo docker logs insforge-postgrest
sudo docker logs insforge-deno

Check whether PostgreSQL is reachable from the container:

sudo docker exec insforge-postgrest bash -c '</dev/tcp/10.10.10.10/5432'

Check whether the HBA rules include the Docker network:

sudo -iu postgres psql -d insforge -c "TABLE pg_hba_file_rules;"

Check whether the roles exist:

sudo -iu postgres psql -d insforge -c "SELECT rolname, rolcanlogin, rolbypassrls FROM pg_roles WHERE rolname IN ('anon','authenticated','project_admin');"

Check for port conflicts:

ss -tlnp | grep -E '7130|7133|5430'

Common issues:

• Cannot log in: Verify ROOT_ADMIN_USERNAME / ROOT_ADMIN_PASSWORD in /opt/insforge/.env. Check the insforge container logs.
• PostgREST fails to start: Verify that anon, authenticated, and project_admin exist. Verify that JWT_SECRET matches the InsForge App setting.
• Database connection fails: Verify POSTGRES_HOST, POSTGRES_PORT, and POSTGRES_PASSWORD against pg_users. Verify that HBA permits the Docker network.
• File upload or download errors: When using S3 / MinIO, check AWS_S3_BUCKET, S3_ENDPOINT_URL, S3_FORCE_PATH_STYLE, and the access-key configuration.

References

• InsForge project: https://github.com/InsForge/InsForge
• Pigsty template: https://github.com/pgsty/pigsty/blob/main/conf/app/insforge.yml
• Docker Compose: https://github.com/pgsty/pigsty/blob/main/app/insforge/docker-compose.yml
• Database baseline: https://github.com/pgsty/pigsty/blob/main/files/insforge.sql

5 - Hindsight: AI Long-Term Memory

Hindsight is a PostgreSQL-native long-term memory service for AI agents.

Pigsty provides the app/hindsight configuration template (conf/app/hindsight.yml). By default, it uses Pigsty-managed PostgreSQL instead of Hindsight’s built-in development database.

Quick Start

curl -fsSL https://repo.pigsty.io/get | bash; cd ~/pigsty
./bootstrap
./configure -c app/hindsight
vi pigsty.yml                 # edit domain, database password, and LLM settings
./deploy.yml
./docker.yml
./app.yml

Default access URLs:

• UI: http://hs.pigsty or http://<IP>:9999
• API: http://hs-api.pigsty or http://<IP>:8888

Key Settings

conf/app/hindsight.yml overrides /opt/hindsight/.env through apps.hindsight.conf. Key parameters:

• HINDSIGHT_API_PUBLISH_PORT: public API port, default 8888
• HINDSIGHT_UI_PUBLISH_PORT: public UI port, default 9999
• HINDSIGHT_DB_HOST / HINDSIGHT_DB_PORT / HINDSIGHT_DB_NAME / HINDSIGHT_DB_USER / HINDSIGHT_DB_PASSWORD
• HINDSIGHT_API_VECTOR_EXTENSION: default pgvector
• HINDSIGHT_API_TEXT_SEARCH_EXTENSION: default native
• HINDSIGHT_API_LLM_PROVIDER: default none
• HF_HUB_OFFLINE: defaults to 1 to use bundled models; set it to 0 and provide outbound network access to download uncached models

With the default LLM provider, none, Hindsight can retain text and recall it using local embedding/reranker models. Fact extraction, reflection, and consolidation require Ollama or an OpenAI-compatible API.

The template preserves bundled and downloaded models in the hindsight-cache named volume. The database needs vector, plus pg_trgm installed in public. Check the pg_trgm location when reusing a database from another template; CREATE EXTENSION IF NOT EXISTS does not move an existing extension.

Operations

cd /opt/hindsight
make up
make log
make info
make down
make pull

References

• Hindsight project: https://github.com/vectorize-io/hindsight
• Pigsty template: https://github.com/pgsty/pigsty/blob/main/conf/app/hindsight.yml

6 - FerretDB: MongoDB Protocol

FerretDB provides a MongoDB-compatible protocol over PostgreSQL and the DocumentDB extension. Pigsty’s app/ferretdb runs the stateless protocol proxy. PostgreSQL, the postgres database, DocumentDB extensions, and a backend PostgreSQL login role must already exist. The fork/mongo configuration template prepares these dependencies together.

Quick Start

curl -fsSL https://repo.pigsty.io/get | bash; cd ~/pigsty
./bootstrap
./configure -c fork/mongo
./deploy.yml
./docker.yml -l pg-meta
./app.yml -l pg-meta

Install mongosh or another MongoDB-compatible client separately. Then connect with the dedicated login from the template:

mongosh 'mongodb://mongod:[email protected]:27017/'

Key Configuration

Override template variables through apps.ferretdb.conf in the inventory. Do not edit the deployed /opt/ferretdb/.env directly:

app: ferretdb
apps:
  ferretdb:
    conf:
      FERRETDB_IMAGE: ghcr.io/ferretdb/ferretdb:2.7.0
      FERRETDB_POSTGRESQL_URL: 'postgres://mongod:[email protected]:5436/postgres?pool_min_conns=1&pool_max_conns=20'
      FERRETDB_BIND_ADDR: 127.0.0.1
      FERRETDB_PORT: 27017
      FERRETDB_AUTH: true
      FERRETDB_TELEMETRY: disabled

Port 5436 is Pigsty’s PostgreSQL service that connects directly to the current primary. Linux host-gateway mapping connects the container through the local host and retains this primary routing. The MongoDB port listens on loopback by default. Change FERRETDB_BIND_ADDR explicitly only when remote clients need access.

FerretDB authenticates users through PostgreSQL. It does not currently implement MongoDB authorization, so MongoDB roles cannot isolate access. The template also does not enable MongoDB client TLS. Before exposing the service to an untrusted network, configure certificates and the FERRETDB_LISTEN_TLS* variables.

FerretDB releases specify a preferred DocumentDB version, while Pigsty may ship a newer compatible package. After upgrading either component, rerun an authenticated CRUD smoke test.

Optional Three-Node Topology

The fork/mongo template includes a commented three-node PostgreSQL / DocumentDB cluster. Each node runs a FerretDB container. HAProxy exposes port 27017 at the floating endpoint 10.10.10.4:27017 (mongo.pigsty). Enable the complete pg-mongo cluster and the additional etcd members, then run:

./configure -c fork/mongo
./deploy.yml
./docker.yml -l pg-mongo
./app.yml -l pg-mongo
mongosh 'mongodb://mongod:[email protected]:27017/'

HAProxy uses TCP health checks to exclude stopped or unreachable FerretDB processes. The image’s built-in health check verifies the backend connection. Production deployments should use a shared Silo or external S3-compatible pgBackRest repository. This keeps the same backup history available after a PostgreSQL primary failover.

References

• PostgreSQL Mongo configuration template
• Pigsty FerretDB template source
• FerretDB documentation

7 - Teable: AI No-Code Database

Teable is a no-code database platform for team collaboration.

Pigsty provides the app/teable template (conf/app/teable.yml). Its default dependencies are PostgreSQL + Silo + Docker. It does not require Redis.

Quick Start

curl -fsSL https://repo.pigsty.io/get | bash; cd ~/pigsty
./bootstrap
./configure -c app/teable
vi pigsty.yml                 # update passwords, domain, and mail settings
./deploy.yml                  # deploy infra, PostgreSQL, and Silo
./docker.yml
./app.yml

Default endpoints:

• http://<IP>:8890
• http://tea.pigsty

Key Settings

The template writes the following into /opt/teable/.env:

• POSTGRES_HOST/POSTGRES_PORT/POSTGRES_DB/POSTGRES_USER/POSTGRES_PASSWORD
• PRISMA_DATABASE_URL
• PUBLIC_ORIGIN (public URL)
• PUBLIC_DATABASE_PROXY
• TEABLE_PORT (default 8890)

Operations

cd /opt/teable
make up
make log
make down

References

• Teable docs: https://help.teable.io/
• Pigsty template: https://github.com/pgsty/pigsty/blob/main/conf/app/teable.yml

8 - Gitea: Self-Hosted Git Service

Gitea is a lightweight open-source Git hosting platform.

Pigsty’s app/gitea template uses external PostgreSQL mode by default. Configure the database through GITEA_DB_* values in .env.

Quick Start

cd ~/pigsty/app/gitea
vi .env         # check domain, ports, database settings
make up

Default endpoints:

• Web: http://git.pigsty or http://<IP>:8889
• SSH: <IP>:222

Database Preparation

bin/pgsql-user pg-meta dbuser_gitea
bin/pgsql-db   pg-meta gitea

Connection string example:

postgres://dbuser_gitea:[email protected]:5432/gitea

Reverse Proxy and Upgrades

Gitea 28 serves notifications at /-/ws. Enable WebSocket support on the Nginx portal:

infra_portal:
  gitea: { domain: git.pigsty, endpoint: "127.0.0.1:8889", websocket: true }

Before upgrading, back up PostgreSQL and /data/gitea together and record the running image digest. Restore matching database and file backups when rolling back. Gitea 28 defaults to removing completed Actions runs, logs, and artifacts after 400 days; check retention settings if those records need to be kept longer. See the Gitea 28 release notes.

Common Commands

make up
make log
make stop
make clean

References

• Gitea docs: https://docs.gitea.com/
• Pigsty template: https://github.com/pgsty/pigsty/tree/main/app/gitea

9 - NocoDB: Open-Source Airtable

NocoDB is an open-source Airtable alternative that turns any database into a smart spreadsheet.

Use its visual interface to create database applications without code. NocoDB supports PostgreSQL, MySQL, SQL Server, and other databases. You can use it for internal tools and data management systems.

Quick Start

Pigsty provides a Docker Compose configuration file for NocoDB in the software template directory:

cd ~/pigsty/app/nocodb

Review and modify the .env configuration file (adjust database connections as needed).

Start the service:

make up     # Start NocoDB with Docker Compose

Access NocoDB:

• Default URL: http://nocodb.pigsty
• Alternate URL: http://10.10.10.10:8080
• First-time access requires creating an administrator account

Management Commands

Use these Makefile commands to manage NocoDB:

make up      # Start NocoDB service
make run     # Start with Docker (connect to external PostgreSQL)
make view    # Display NocoDB access URL
make log     # View container logs
make info    # View service details
make stop    # Stop the service
make clean   # Stop and remove containers
make pull    # Pull the latest image
make rmi     # Remove NocoDB image
make save    # Save image to /tmp/nocodb.tgz
make load    # Load image from /tmp/nocodb.tgz

Connect to PostgreSQL

NocoDB can connect to PostgreSQL databases managed by Pigsty.

When adding a new project in the NocoDB interface, select “External Database” and enter the PostgreSQL connection information:

Host: 10.10.10.10
Port: 5432
Database Name: your_database
Username: your_username
Password: your_password
SSL: Disabled (or enable as needed)

After connecting, NocoDB reads the table structure automatically. You can then manage data through the visual interface.

Features

• Smart Spreadsheet Interface: Excel/Airtable-like user experience
• Multiple Views: Grid, form, kanban, calendar, gallery views
• Collaboration Features: Team collaboration, permission management, comments
• API Support: Auto-generated REST API
• Integration Capabilities: Webhooks, Zapier integrations
• Import/Export: CSV, Excel format support
• Formulas and Validation: Complex data calculations and validation rules

Configuration

NocoDB configuration is in the .env file:

# Database connection (NocoDB metadata storage)
NC_DB=pg://postgres:[email protected]:5432/nocodb

# JWT secret (recommended to change)
NC_AUTH_JWT_SECRET=your-secret-key

# Other settings
NC_PUBLIC_URL=http://nocodb.pigsty
NC_DISABLE_TELE=true

Data Persistence

By default, NocoDB stores metadata in external PostgreSQL. It can also store application data in PostgreSQL.

If using local storage, data is saved in the /data/nocodb directory.

Security Recommendations

1. Change Default Secret: Modify NC_AUTH_JWT_SECRET in the .env file
2. Use Strong Passwords: Set strong passwords for administrator accounts
3. Configure HTTPS: Enable HTTPS for production environments
4. Restrict Access: Limit access through firewall or Nginx
5. Regular Backups: Regularly back up the NocoDB metadata database

Related Links

• NocoDB Website: https://nocodb.com/
• Documentation: https://docs.nocodb.com/
• GitHub Repository: https://github.com/nocodb/nocodb
• Pigsty Software Template: https://github.com/pgsty/pigsty/tree/main/app/nocodb

10 - Mattermost: Open-Source Team Collaboration

Mattermost is an open-source team collaboration platform and a private alternative to Slack.

Pigsty provides app/mattermost (conf/app/mattermost.yml). It stores application state in external PostgreSQL and keeps file directories on host paths.

Quick Start

curl -fsSL https://repo.pigsty.io/get | bash; cd ~/pigsty
./bootstrap
./configure -c app/mattermost
vi pigsty.yml                 # update passwords and domain
./deploy.yml
./docker.yml
./app.yml

Default endpoints:

• http://<IP>:8065
• http://mm.pigsty

On first access, initialize the admin account in the web UI.

Default Storage and Connections

Default template settings include:

• PostgreSQL URL: POSTGRES_URL=postgres://dbuser_mattermost:DBUser.Mattermost@<IP>:5432/mattermost?...
• Persistent directories: /data/mattermost/{config,data,logs,plugins,client/plugins,bleve-indexes}

Operations

cd /opt/mattermost
make up
make restart
make log
make stop

References

• Mattermost docs: https://docs.mattermost.com/
• Pigsty template: https://github.com/pgsty/pigsty/blob/main/conf/app/mattermost.yml

11 - Wiki.js: OSS Wiki Software

Public Demo: http://wiki.pigsty.cc

The current Compose uses the untagged requarks/wiki image. Stable 2.x releases are maintained in requarks/wiki-v2; the original requarks/wiki repository contains 3.x Beta releases. The image resolved to 2.5.316 during validation on 2026-10-08. Record and verify the actual image version before production upgrades.

TL; DR

cd ~/pigsty/app/wiki && docker compose up -d

Postgres Preparation

# postgres://dbuser_wiki:[email protected]:5432/wiki
- { name: wiki, owner: dbuser_wiki, revokeconn: true , comment: wiki the api gateway database }
- { name: dbuser_wiki, password: DBUser.Wiki , pgbouncer: true , roles: [ dbrole_admin ] }

bin/pgsql-user pg-meta dbuser_wiki
bin/pgsql-db   pg-meta wiki

Configuration

services:
  wiki:
    container_name: wiki
    image: requarks/wiki
    environment:
      DB_TYPE: postgres
      DB_HOST: 10.10.10.10
      DB_PORT: 5432
      DB_USER: dbuser_wiki
      DB_PASS: DBUser.Wiki
      DB_NAME: wiki
    restart: unless-stopped
    ports:
      - "9002:3000"

Access

• Default Port for wiki: 9002

infra_portal:
  wiki: { domain: wiki.pigsty.io, endpoint: "127.0.0.1:9002" }

./infra.yml -t nginx_config,nginx_reload -l infra

12 - Maybe: Self-Hosted Personal Finance

Maybe is an open-source personal finance application. It manages accounts, transactions, budgets, investments, and household financial views. This Rails application stores production business data in PostgreSQL and uses Redis for background job queues.

Pigsty’s app/maybe template connects stateless Maybe Web / Worker containers to Pigsty-managed PostgreSQL. Local Redis provides the Sidekiq queue. Financial data resides in a PostgreSQL cluster with backup, monitoring, and recovery support, rather than an ephemeral Docker volume.

The upstream Maybe repository has been archived, and its latest release is v0.6.0. GHCR currently publishes stable and latest image tags. Pigsty uses stable by default, which tracks the latest release image.

Quick Start

Run the following on a fresh Linux x86 / ARM server with a compatible operating system:

curl -fsSL https://repo.pigsty.io/get | bash; cd ~/pigsty
./bootstrap                # Install Pigsty dependencies
./configure -c app/maybe   # Use the Maybe configuration template
vi pigsty.yml              # Required: SECRET_KEY_BASE, database password, domain

./deploy.yml               # Install Pigsty, Infra, Etcd, and PostgreSQL
./docker.yml               # Install Docker and Compose
./app.yml                  # Install Maybe

Maybe listens on port 5002 by default. After installation, you can access it at:

• http://<your_ip_address>:5002
• http://maybe.pigsty

On the first visit, select the account creation option on the login page. Register your first household account.

To access Maybe through maybe.pigsty, add the following entry to /etc/hosts on the machine running your browser:

10.10.10.10 maybe.pigsty

To expose the service to the public internet, use a real domain and HTTPS certificate, and modify infra_portal as described below.

Checklist

• Prepare a fresh Linux server with at least 2C4G; use an SSD/NVMe disk.
• Confirm that the server has a static private IPv4 address and can access GHCR / Docker Hub, or that a registry mirror is configured.
• After running ./configure -c app/maybe, change the default passwords, domain, and secrets in pigsty.yml.
• Generate a new SECRET_KEY_BASE with openssl rand -hex 64.
• Keep POSTGRES_PASSWORD consistent with the password of the maybe user in pg_users.
• For public access, configure a real domain, an HTTPS certificate, and firewall access rules.
• Confirm that PostgreSQL backup jobs run correctly, and check pig pb info after deployment.

Configuration Template

conf/app/maybe.yml defines a single-node, self-hosted Maybe template. The default topology includes:

• maybe: The node running the Maybe Web / Worker / Redis containers.
• pg-maybe: The PostgreSQL database cluster managed by Pigsty.
• infra: Infrastructure services such as Nginx ingress, Grafana, and VictoriaMetrics.
• etcd: The distributed configuration store required by Patroni.

Key configuration excerpts:

maybe:
  hosts: { 10.10.10.10: {} }
  vars:
    app: maybe
    apps:
      maybe:
        file:
          - { path: /data/maybe             ,state: directory ,mode: 0755 }
          - { path: /data/maybe/storage     ,state: directory ,owner: 1000 ,group: 1000 ,mode: 0755 }
          - { path: /data/maybe/redis       ,state: directory ,mode: 0755 }
        conf:
          MAYBE_IMAGE: ghcr.io/maybe-finance/maybe
          MAYBE_VERSION: stable
          MAYBE_PORT: 5002
          MAYBE_DATA: /data/maybe
          APP_DOMAIN: maybe.pigsty
          SECRET_KEY_BASE: 2f1e4c3d5b6a79808796a5b4c3d2e1f00123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef01234567
          DB_HOST: 10.10.10.10
          DB_PORT: 5432
          POSTGRES_USER: maybe
          POSTGRES_PASSWORD: MaybeFinance2026
          POSTGRES_DB: maybe_production
          REDIS_VERSION: 7-alpine

pg-maybe:
  hosts: { 10.10.10.10: { pg_seq: 1, pg_role: primary } }
  vars:
    pg_cluster: pg-maybe
    pg_users:
      - { name: maybe ,password: MaybeFinance2026 ,pgbouncer: true ,roles: [ dbrole_admin ] ,comment: admin user for maybe service }
    pg_databases:
      - { name: maybe_production ,owner: maybe ,revokeconn: true ,comment: maybe main database }
    pg_hba_rules:
      - { user: maybe ,db: maybe_production ,addr: 172.16.0.0/12 ,auth: pwd ,title: 'allow maybe access from local docker network' }
    pg_crontab: [ '00 01 * * * /pg/bin/pg-backup full' ]

Maybe / Rails uses maybe_production as its default production database name. You can rename it to maybe. Update POSTGRES_DB, pg_databases.name, pg_hba_rules.db, and all documentation and operational script references together.

Important Parameters

app.yml copies the app/maybe directory to /opt/maybe and uses apps.maybe.conf to override /opt/maybe/.env. Common parameters include:

Generate a production secret with:

openssl rand -hex 64

When changing the password, keep the application and database definitions synchronized. For example:

apps:
  maybe:
    conf:
      POSTGRES_PASSWORD: <new-password>

pg_users:
  - { name: maybe ,password: <new-password> ,pgbouncer: true ,roles: [ dbrole_admin ] }

Domain and Ingress

The template adds a Maybe entry to infra_portal by default:

infra_portal:
  home  : { domain: i.pigsty }
  maybe:
    domain: maybe.pigsty
    endpoint: "10.10.10.10:5002"
    websocket: true

To use a real domain such as finance.example.com, replace the placeholder in bulk:

sed -ie 's/maybe.pigsty/finance.example.com/g' pigsty.yml

Then apply the Nginx ingress configuration:

./infra.yml -t nginx

Before requesting an HTTPS certificate, verify that the domain resolves to the current node. Then add certbot under infra_portal.maybe:

maybe:
  domain: finance.example.com
  endpoint: "10.10.10.10:5002"
  websocket: true
  certbot: finance.example.com

Then run:

make cert
./infra.yml -t nginx

Operations

Maybe is installed in /opt/maybe. Common commands include:

cd /opt/maybe

make up        # Start Maybe
make run       # Start in the foreground and show logs
make restart   # Restart containers
make down      # Stop containers
make status    # Show container status
make log       # Follow logs
make health    # Check the Rails /up health endpoint
make migrate   # Run Rails db:prepare manually
make console   # Enter the Rails console
make exec      # Enter a shell in the maybe-web container

The web container runs db:prepare at startup, so manual migration is usually unnecessary. After an image upgrade, inspect any migration errors in startup logs. Then run:

cd /opt/maybe
make pull
make up
make log

Data and Backup

Maybe state is divided into two categories:

• Business data is stored in the Pigsty PostgreSQL database maybe_production.
• Attachments and cache are stored in the host directories /data/maybe/storage and /data/maybe/redis.

By default, the template schedules a full PostgreSQL backup every day at 1:00 AM:

pg_crontab: [ '00 01 * * * /pg/bin/pg-backup full' ]

After deployment, check the backup status:

pig pb info

If you use Maybe to store real financial data in production, at minimum:

• Regularly verify that PostgreSQL backups succeed.
• Place the pgBackRest repository on reliable storage or object storage.
• Include /data/maybe/storage in file-level backups; for example, use restic to back it up to S3.
• Do not expose SECRET_KEY_BASE, database passwords, or API keys in a public repository.

Security Recommendations

Maybe manages highly sensitive personal and household financial data. For production use:

• Change all Pigsty default passwords, especially pg_admin_password, pg_monitor_password, patroni_password, and haproxy_admin_password.
• Change the Maybe database user password in POSTGRES_PASSWORD.
• Use a new SECRET_KEY_BASE; do not retain the sample value from the template.
• Enable HTTPS for public access and restrict access to administration ports.
• If you enable OPENAI_ACCESS_TOKEN or SYNTH_API_KEY, assess both external API costs and the boundary of data exposure.

The upstream Maybe repository is archived. It suits users who accept the existing features and prefer long-term local ownership. If you need new features or automatic bank synchronization, evaluate upstream maintenance before adoption.

References

• Maybe project: https://github.com/maybe-finance/maybe
• Maybe Docker self-hosting guide: https://github.com/maybe-finance/maybe/blob/main/docs/hosting/docker.md
• Pigsty Maybe template: https://github.com/pgsty/pigsty/blob/main/conf/app/maybe.yml
• Pigsty Docker module
• Pigsty Nginx ingress

13 - Immich: Self-Hosted Photo and Video Library

Immich is a high-performance, self-hosted photo and video management application. It is a popular open-source alternative to Google Photos, licensed under AGPL-3.0. Features include web and mobile uploads, album sharing, timelines, maps, EXIF and RAW support, and LivePhoto. It also provides semantic search, facial recognition, and automatic backups.

Pigsty’s app/immich template runs the Immich application layer with Docker Compose and stores metadata in Pigsty-managed PostgreSQL. The template follows Immich v3 and uses VectorChord by default for similar-image search, smart search, and face-search vectors. On 2026-10-08, both Server and ML images resolved to 3.3.0. Validation used a new media library on Linux amd64 with PostgreSQL 18.6 and covered uploads, thumbnails, and real machine-learning inference.

Immich’s official single-node Compose template runs PostgreSQL in an application container. Pigsty manages PostgreSQL separately, with monitoring, backups, PITR, extension management, and high-availability access.

Quick Start

Immich recommends at least 2 CPU cores and 6 GB RAM. For smooth operation, it recommends 4 CPU cores and 8 GB RAM. The v3 amd64 machine-learning image requires x86-64-v2 instructions. Linux with local SSD storage is recommended for production.

On a fresh x86 or ARM Linux server running a compatible operating system:

curl -fsSL https://repo.pigsty.io/get | bash; cd ~/pigsty
./bootstrap
./configure -c app/immich
vi pigsty.yml              # Required: change passwords, domains, and media paths

./deploy.yml               # Install Pigsty and PostgreSQL
./docker.yml               # Install Docker and Compose
./app.yml                  # Install Immich

Default endpoints:

http://photo.pigsty
http://10.10.10.10:2283

If you use photo.pigsty, add a hosts entry on the browser host or replace the template domain with a real domain.

Template Structure

conf/app/immich.yml defines a single-node self-hosted Immich template. The default topology includes:

• immich: the node running Immich Server, Machine Learning, and local Valkey/Redis containers.
• pg-immich: the Pigsty-managed PostgreSQL cluster.
• infra: Nginx ingress, Grafana, VictoriaMetrics, and other infrastructure.
• etcd: the distributed configuration store required by Patroni.

Application containers include:

• immich-server: API, Web UI, and background jobs, exposed on host port 2283 by default.
• immich-machine-learning: CLIP and facial-recognition model inference.
• redis: local Valkey queues and cache.

The template does not start the PostgreSQL container from Immich’s upstream Compose file. Pigsty provides the database through DB_URL.

Data Storage Strategy

Immich state is divided into three layers that must be managed separately:

• Media files: original photos and videos, thumbnails, transcoded videos, avatars, and the upload queue, stored in the host directory specified by UPLOAD_LOCATION.
• PostgreSQL: metadata for users, albums, assets, EXIF, file paths, job state, people, faces, and smart-search vectors.
• Valkey/Redis: queues, cache, and runtime state; it must not be treated as an authoritative data source.

Photo and video files are not stored in PostgreSQL. Rescanning the media directory cannot reconstruct complete application state. Database paths and metadata are also required.

A recoverable Immich backup requires both PostgreSQL and the media directory. A database-only backup omits photos. A file-only backup cannot reliably restore albums, users, shares, faces, and search state.

PostgreSQL

Default database connection and vector extension:

DB_URL=postgresql://dbuser_immich:[email protected]:5432/immich
DB_VECTOR_EXTENSION=vectorchord

The template installs the extension packages on the pg-immich cluster and creates the database extensions:

CREATE EXTENSION vchord CASCADE;
CREATE EXTENSION earthdistance CASCADE;
CREATE EXTENSION pg_trgm WITH SCHEMA public;

vchord must be added to shared_preload_libraries through pg_libs; the template already configures it:

pg_extensions: [ pgvector, vchord ]
pg_libs: 'vchord.so, pg_stat_statements, auto_explain'

pg_trgm must be in public because Immich migrations reference gin_trgm_ops without a schema qualifier. Check its location when reusing a database from another template; CREATE EXTENSION IF NOT EXISTS does not move an installed extension.

The default connection goes directly to PostgreSQL on port 5432. Do not point Immich at PgBouncer transaction pooling. Direct PostgreSQL connections or session pooling are more reliable for migrations, indexes, and prepared statements.

Immich treats pre-existing PostgreSQL as an advanced deployment option. It notes that this enables WAL backup tools such as pgBackRest and Barman. Pigsty creates the database, user, and extensions in advance. The Immich application user therefore does not need PostgreSQL superuser privileges.

Media Files

Uploaded photos, videos, thumbnails, transcoded files, and avatars are stored in the host directory specified by UPLOAD_LOCATION:

/data/immich/library

PostgreSQL stores only metadata and file paths. Media files are not stored in PostgreSQL and are not automatically protected by pgBackRest.

A production deployment must back up at least two data layers:

• PostgreSQL: use Pigsty pgBackRest / PITR.
• Media files: perform a complete file-level backup of /data/immich/library, including originals, the upload queue, thumbnails, transcoded files, avatars, and other generated assets.

For a more consistent combined backup, stop immich-server before backing up the database and media directory together. If the service cannot be stopped, back up the database first, followed by the filesystem.

Images and Networking

The default images come from GHCR and Docker Hub:

docker pull ghcr.io/immich-app/immich-server:v3
docker pull ghcr.io/immich-app/immich-machine-learning:v3
docker pull docker.io/valkey/valkey:9@sha256:c123e3715db63d06d4ad6964884037aa0d5d4d703939b9929954112889708e1d

The Valkey digest matches the Immich 3.3.0 release Compose. Both make pull and make save resolve the same image reference from Compose.

If pulls are slow or restricted, configure the Docker daemon proxy; shell proxy_env alone does not configure Docker image pulls. Docker Hub mirrors do not cover GHCR. Use docker compose config --images to check the resolved image set.

Operations

After installation, enter /opt/immich:

cd /opt/immich

make up       # Start Immich
make logs     # Follow logs
make info     # Show container status
make pull     # Pull images
make restart  # Restart containers
make down     # Stop and remove containers

To pin a specific Immich version, set the following in pigsty.yml:

IMMICH_VERSION: v3.3.0  # optional exact pin; the template defaults to v3

Read the upstream release notes before upgrading Immich or VectorChord. After a VectorChord package upgrade, you will usually need to update the extension and rebuild related indexes in immich:

ALTER EXTENSION vchord UPDATE;
REINDEX INDEX face_index;
REINDEX INDEX clip_index;

Rebuilding indexes for a large library can take a long time. Confirm that you have a backup and a maintenance window before proceeding.

References

• Immich project: https://github.com/immich-app/immich
• Immich pre-existing PostgreSQL: https://docs.immich.app/administration/postgres-standalone/
• Immich backup and restore: https://docs.immich.app/administration/backup-and-restore/
• Pigsty Immich template: https://github.com/pgsty/pigsty/blob/main/conf/app/immich.yml
• Pigsty Docker module
• Pigsty Nginx ingress

14 - Kong: API Gateway

Kong is an open-source API gateway.

Pigsty’s app/kong template stores configuration in PostgreSQL. It automatically runs the one-time kong-migration job.

Quick Start

cd ~/pigsty/app/kong
vi .env         # check KONG_PG_* and port settings
make

Default ports:

• Proxy HTTP: 8000
• Proxy HTTPS: 8443
• Admin API: 8001

Database Preparation

bin/pgsql-user pg-meta dbuser_kong
bin/pgsql-db   pg-meta kong

Connection string example:

postgres://dbuser_kong:[email protected]:5432/kong

Common Commands

make log
make stop
make clean
make pull

References

• Kong docs: https://docs.konghq.com/
• Pigsty template: https://github.com/pgsty/pigsty/tree/main/app/kong

15 - Metabase: BI Analytics Tool

Metabase is an open-source business intelligence tool. Teams can quickly explore and visualize data through its interface without SQL knowledge.

Metabase provides many chart types and connects to different databases. These features support enterprise data analysis.

The template defaults to metabase/metabase:v0.64.1.x. Use the single METABASE_IMAGE setting to override the full image reference. On 2026-10-08, the tag resolved to 0.64.1.1; validation on PostgreSQL 18.6 covered upgrading a restored metadata database, login, and querying an existing saved question.

Quick Start

Pigsty provides a Docker Compose configuration file for Metabase in the software template directory:

cd ~/pigsty/app/metabase

Review and modify the .env configuration file:

vim .env    # Check configuration, recommend changing default credentials

Before starting, create a dedicated metabase database and dbuser_metabase role matching the .env connection settings. Do not share the Pigsty CMDB database.

Start the service:

make up     # Start Metabase with Docker Compose

Access Metabase:

• Default URL: http://mtbs.pigsty
• Alternate URL: http://10.10.10.10:9004
• First-time access requires initial setup

Management Commands

Use these Makefile commands to manage Metabase:

make up      # Start Metabase service
make run     # Alias for make up
make view    # Display Metabase access URL
make log     # View container logs
make info    # View service details
make stop    # Stop the service
make clean   # Stop and remove containers
make pull    # Pull the configured image
make rmi     # Remove Metabase image
make save    # Save image to file
make load    # Load image from file

Connect to PostgreSQL

Metabase can connect to PostgreSQL databases managed by Pigsty.

During Metabase initialization or when adding a database, select “PostgreSQL” and enter the connection information:

Database Type: PostgreSQL
Name: Custom name (e.g., "Production Database")
Host: 10.10.10.10
Port: 5432
Database Name: your_database
Username: dbuser_meta
Password: DBUser.Meta

After connecting, Metabase scans the database schema automatically. You can then create questions and dashboards.

Features

• No SQL Required: Build queries through visual interface
• Rich Chart Types: Line, bar, pie, map charts, and more
• Interactive Dashboards: Create interactive data dashboards
• Auto Refresh: Schedule data and dashboard updates
• Permission Management: Fine-grained user and data access control
• SQL Mode: Advanced users can write SQL directly
• Embedding: Embed charts into other applications
• Alerting: Automatic notifications on data changes

Configuration

Metabase configuration is in the .env file:

# Image and host port
METABASE_IMAGE=metabase/metabase:v0.64.1.x
MB_PORT=9004

# Metabase metadata database
MB_DB_TYPE=postgres
MB_DB_DBNAME=metabase
MB_DB_PORT=5432
MB_DB_USER=dbuser_metabase
MB_DB_PASS=DBUser.Metabase
MB_DB_HOST=10.10.10.10

Recommended: Use a dedicated PostgreSQL database for storing Metabase metadata.

Data Persistence

Metabase metadata (users, questions, dashboards, etc.) is stored in the configured database.

The template uses external PostgreSQL by default and does not configure a persistent /data/metabase directory for H2. Its /api/health check covers both the application and metadata database. Wait for healthy status during initial migrations.

Upgrading from Metabase 63 to 64 automatically migrates the metadata database. Back it up and record the old image digest first, then test on a restored copy. Rollback requires the matching database backup and old image; replacing the image alone does not undo database migrations. See the upgrade guide.

Performance Optimization

• Use PostgreSQL: Allocate separate resources for the metadata database and monitor its workload
• Increase Memory: Pass JAVA_OPTS explicitly in Compose’s environment to tune JVM memory; adding it to .env alone does not pass it into the container
• Database Indexes: Create indexes for frequently queried fields
• Result Caching: Enable Metabase query result caching
• Scheduled Updates: Set reasonable dashboard auto-refresh frequency