chore: include tn_vacuum extension

Taskfile.yml

@@ -96,7 +96,7 @@ tasks:
   host:postgres:start:
     desc: Run a postgres container
     cmds:
-      - docker start kwil-postgres || docker run -d -p 5432:5432 --name kwil-postgres -e "POSTGRES_HOST_AUTH_METHOD=trust" kwildb/postgres:latest
+      - docker start kwil-postgres || docker run -d -p 5432:5432 --name kwil-postgres -e "POSTGRES_HOST_AUTH_METHOD=trust" ghcr.io/trufnetwork/kwil-postgres:latest
 
   host:indexer:start:
     desc: Run the indexer

compose.yaml

@@ -1,6 +1,6 @@
 services:
   kwil-postgres:
-    image: "kwildb/postgres:16.8-1"
+    image: "ghcr.io/trufnetwork/kwil-postgres:16.8-1"
     hostname: kwil-postgres
     shm_size: 2G
     restart: unless-stopped
@@ -28,7 +28,7 @@ services:
   tn-db:
     container_name: tn-db
     hostname: tn-db
-    image: "ghcr.io/trufnetwork/node:local"
+    image: "ghcr.io/trufnetwork/node:${TN_IMAGE:-local}"
     restart: unless-stopped
     build:
       context: .
@@ -37,9 +37,9 @@ services:
       CONFIG_PATH: /root/.kwild
       # app.pg-db-host
       KWILD_DB_HOST: kwil-postgres
-      # Optionally supply SETUP_DB_OWNER to override the owner derived from the generated node key
-      SETUP_DB_OWNER: ${SETUP_DB_OWNER:-}
-      SETUP_CHAIN_ID: ${SETUP_CHAIN_ID:-trufnetwork-dev}
+      # Optionally supply SETUP_DB_OWNER to override the owner derived from the generated node key
+      SETUP_DB_OWNER: ${SETUP_DB_OWNER:-}
+      SETUP_CHAIN_ID: ${SETUP_CHAIN_ID:-trufnetwork-dev}
     ports:
       - "50051:50051"
       - "${TN_RPC_PORT:-8484}:8484"

deployments/Dockerfile

@@ -17,10 +17,20 @@ COPY deployments/tn-entrypoint.sh ./deployments/tn-entrypoint.sh
 # todo: incorporate task build process, otherwise images will lack information about the build
 RUN CGO_ENABLED=0 GOOS=linux GOARCH=amd64 go build -o /app/.build/kwild /app/cmd/kwild/main.go
 
-FROM busybox:1.35.0-uclibc as busybox
-# busy box will provide us with a shell to run commands in distroless
+FROM postgres:16-alpine AS pg_repack_builder
 
-FROM alpine:latest
+# build pg_repack against postgres 16 client libraries
+RUN apk add --no-cache build-base clang19 gawk llvm19 curl zlib-dev readline-dev openssl-dev lz4-dev zstd-dev && \
+    curl -fsSL -o /tmp/pg_repack.tar.gz https://codeload.github.com/reorg/pg_repack/tar.gz/refs/tags/ver_1.5.2 && \
+    tar -xzf /tmp/pg_repack.tar.gz && rm /tmp/pg_repack.tar.gz && \
+    cd pg_repack-ver_1.5.2 && \
+    make USE_PGXS=1 PG_CONFIG=/usr/local/bin/pg_config && \
+    make USE_PGXS=1 PG_CONFIG=/usr/local/bin/pg_config install && \
+    PG_BINDIR="$(/usr/local/bin/pg_config --bindir)" && \
+    install -Dm755 "$PG_BINDIR/pg_repack" /opt/pg_repack/bin/pg_repack && \
+    cd .. && rm -rf pg_repack-ver_1.5.2
+
+FROM alpine:3.21
 
 ENV SETUP_CHAIN_ID=truflation-dev
 ENV SETUP_DB_OWNER=
@@ -29,9 +39,12 @@ ENV CONFIG_PATH=/root/.kwild
 
 WORKDIR /app
 
-# add postgres client tools
+# add postgres client tools and the pg_repack binary used by tn_vacuum
 RUN apk add --no-cache postgresql16-client
 
+# copy pg_repack CLI from build stage
+COPY --from=pg_repack_builder /opt/pg_repack/bin/pg_repack /usr/local/bin/pg_repack
+
 # move .build content to /app
 COPY --from=build /app/.build/* /app/
 

deployments/dev-net/devnet-compose.yaml

@@ -33,7 +33,7 @@ x-common-logging: &common_logging
 
 services:
   kwil-postgres-1:
-    image: "kwildb/postgres:16.8-1"
+    image: "ghcr.io/trufnetwork/kwil-postgres:16.8-1"
     ports:
       - "5432:5432"
     <<: *postgres_common
@@ -42,7 +42,7 @@ services:
         source: data-kwil-postgres-1
 
   kwil-postgres-2:
-    image: "kwildb/postgres:16.8-1"
+    image: "ghcr.io/trufnetwork/kwil-postgres:16.8-1"
     ports:
       - "5433:5432"
     <<: *postgres_common

deployments/infra/README.md

@@ -331,7 +331,7 @@ The AMI includes:
 - **Base OS**: Ubuntu 24.04 LTS
 - **Docker**: Latest Docker CE with docker-compose
 - **TRUF.NETWORK Stack**:
-  - PostgreSQL (kwildb/postgres:16.8-1) 
+  - PostgreSQL (ghcr.io/trufnetwork/kwil-postgres:16.8-1) 
   - TRUF.NETWORK Node - ⚠️ To be added when ghcr image is published
   - PostgreSQL MCP Server (crystaldba/postgres-mcp:latest) - Will need to be adjusted later on
 - **Configuration Scripts**:
@@ -382,4 +382,4 @@ aws logs describe-log-groups --log-group-name-prefix /aws/imagebuilder
 
 ## Important
 
-Always use these commands responsibly, especially in non-production environments. Remember to delete the stack after testing to avoid unnecessary AWS charges.
+Always use these commands responsibly, especially in non-production environments. Remember to delete the stack after testing to avoid unnecessary AWS charges.

deployments/infra/stacks/docker-compose.template.yml

@@ -1,6 +1,6 @@
 services:
   tn-postgres:
-    image: kwildb/postgres:latest
+    image: ghcr.io/trufnetwork/kwil-postgres:latest
     container_name: tn-postgres
     environment:
       POSTGRES_HOST_AUTH_METHOD: trust
@@ -106,4 +106,4 @@ services:
 networks:
   tn-network:
     name: tn-network
-    driver: bridge
+    driver: bridge

docs/container-image-guide.md

@@ -7,7 +7,7 @@ Run the TRUF.NETWORK node container with Docker Compose while keeping the standa
 
 ## Prerequisites
 - Docker Engine 24+ with the `docker compose` plugin.
-- Pull access to `ghcr.io/trufnetwork/node` and `kwildb/postgres`.
+- Pull access to `ghcr.io/trufnetwork/node` and `ghcr.io/trufnetwork/kwil-postgres`.
 - Optional: the [`kwild` CLI](https://github.com/trufnetwork/node/releases) if you want to pre-populate configuration files instead of using the container’s auto-initialization path.
 
 ## 1. Prepare the workspace
@@ -26,7 +26,7 @@ Create `docker-compose.yml` in `~/truf-node` using the minimal stack below.
 ```yaml
 services:
   postgres:
-    image: kwildb/postgres:16.8-1
+    image: ghcr.io/trufnetwork/kwil-postgres:latest
     restart: unless-stopped
     environment:
       POSTGRES_HOST_AUTH_METHOD: trust

docs/examples/mcp-reverse-proxy/README.md

@@ -28,7 +28,7 @@ This directory contains ready-to-use configuration examples for deploying the TR
 2. **Create environment file:**
    ```bash
    cat > .env << EOF
-   # TRUF.NETWORK uses kwildb/postgres image which auto-creates kwild user/database
+   # TRUF.NETWORK uses ghcr.io/trufnetwork/kwil-postgres image which auto-creates kwild user/database
    # Note: No password needed - uses POSTGRES_HOST_AUTH_METHOD=trust
    DOMAIN=mcp.your-domain.com
    ACME_EMAIL=admin@your-domain.com
@@ -276,7 +276,7 @@ Have a working configuration for another reverse proxy? Please contribute:
 git clone https://github.com/trufnetwork/node.git
 cd node/docs/examples/mcp-reverse-proxy
 
-# Configure environment (kwildb/postgres auto-creates kwild user/database)  
+# Configure environment (ghcr.io/trufnetwork/kwil-postgres auto-creates kwild user/database)  
 cat > .env << EOF
 DOMAIN=mcp.your-domain.com
 ACME_EMAIL=admin@your-domain.com
@@ -291,4 +291,4 @@ docker compose logs -f mcp-server
 
 # Test
 curl -H "Accept: text/event-stream" http://your-domain.com/sse
-```
+```

docs/examples/mcp-reverse-proxy/docker-compose.sse.yaml

@@ -13,7 +13,7 @@ version: '3.8'
 services:
   # PostgreSQL Database (Kwil-configured image for TRUF.NETWORK)
   postgres:
-    image: kwildb/postgres:latest
+    image: ghcr.io/trufnetwork/kwil-postgres:latest
     container_name: tn-postgres
     restart: unless-stopped
     environment:
@@ -200,8 +200,8 @@ volumes:
 # Example environment file (.env)
 # Copy to .env and customize:
 #
-# # Database settings (TRUF.NETWORK uses kwildb/postgres image with trust auth)
-# # The kwildb/postgres image automatically creates kwild user and database
+# # Database settings (TRUF.NETWORK uses ghcr.io/trufnetwork/kwil-postgres image with trust auth)
+# # The ghcr.io/trufnetwork/kwil-postgres image automatically creates kwild user and database
 # # Note: No password needed due to POSTGRES_HOST_AUTH_METHOD=trust
 # 
 # # MCP Server settings
@@ -251,4 +251,4 @@ volumes:
 #    docker compose -f docker-compose.sse.yaml down
 #
 # 7. Full cleanup:
-#    docker compose -f docker-compose.sse.yaml down -v --remove-orphans
+#    docker compose -f docker-compose.sse.yaml down -v --remove-orphans

docs/examples/mcp-reverse-proxy/traefik.yml.example

@@ -267,7 +267,7 @@ services:
       - "traefik.http.middlewares.dashboard-auth.basicauth.users=admin:$$apr1$$YOUR_HASHED_PASSWORD_HERE" # Generate with: htpasswd -nb admin your-secure-password
 
   postgres:
-    image: kwildb/postgres:latest
+    image: ghcr.io/trufnetwork/kwil-postgres:latest
     restart: unless-stopped
     environment:
       - POSTGRES_HOST_AUTH_METHOD=trust
@@ -310,4 +310,4 @@ networks:
 
 volumes:
   postgres-data:
-  traefik-logs:
+  traefik-logs:

docs/mcp-reverse-proxy.md

@@ -252,7 +252,7 @@ LoadModule headers_module modules/mod_headers.so
 
 ## MCP Server SSE Configuration
 
-**Important**: TRUF.NETWORK uses the Kwil PostgreSQL Docker image (`kwildb/postgres`) which is configured with `POSTGRES_HOST_AUTH_METHOD=trust` and automatically creates a `kwild` database with a `kwild` user. This matches the standard node setup described in the [Node Operator Guide](./node-operator-guide.md).
+**Important**: TRUF.NETWORK uses the Kwil PostgreSQL Docker image (`ghcr.io/trufnetwork/kwil-postgres`) which is configured with `POSTGRES_HOST_AUTH_METHOD=trust` and automatically creates a `kwild` database with a `kwild` user. This matches the standard node setup described in the [Node Operator Guide](./node-operator-guide.md).
 
 ### Starting the MCP Server with SSE
 
@@ -650,4 +650,4 @@ After implementing reverse proxy configuration:
 4. **Plan Scaling**: Consider load balancing for high-traffic scenarios
 5. **Security Audits**: Regular security reviews and updates
 
-For additional support with MCP server deployment, consult the [Node Operator Guide](./node-operator-guide.md) and [MCP Server Documentation](./mcp-server.md).
+For additional support with MCP server deployment, consult the [Node Operator Guide](./node-operator-guide.md) and [MCP Server Documentation](./mcp-server.md).

docs/node-operator-guide.md

@@ -56,15 +56,15 @@ The PostgreSQL client (`psql`) is required for database operations, and the `pg_
 #### For Linux (Ubuntu/Debian)
 
 ```bash
-sudo apt-get install -y postgresql-client-16
+sudo apt-get install -y postgresql-client-16 postgresql-16-repack
 ```
 
 #### For macOS
 
 You can install the PostgreSQL client using [Homebrew](https://brew.sh/). If you don't have Homebrew, install it first by following the instructions on their website.
 
 ```bash
-brew install postgresql@16
+brew install postgresql@16 pg_repack
 ```
 
 To use it from any terminal, you may need to add it to your `PATH`. For `zsh` (the default in modern macOS):
@@ -226,7 +226,7 @@ docker run -d -p 127.0.0.1:5432:5432 --name tn-postgres \
     -e "POSTGRES_HOST_AUTH_METHOD=trust" \
     -v tn-pgdata:/var/lib/postgresql/data \
     --shm-size=1gb \
-    kwildb/postgres:latest
+    ghcr.io/trufnetwork/kwil-postgres:latest
 ```
 
 > **Warning**: Critical Security Requirements
@@ -487,6 +487,26 @@ For complete configuration options (stream lists, schedules, metrics, troublesho
 
 [extensions/tn_cache/README.md#operations--monitoring](../extensions/tn_cache/README.md#operations--monitoring)
 
+### Vacuum Extension (tn_vacuum)
+
+The `tn_vacuum` extension provides **automated database maintenance** through periodic vacuuming operations. It helps reclaim disk space and optimize database performance by removing dead tuples using `pg_repack`.
+
+> **Note:** If you're using the official TrufNetwork node image, `pg_repack` is already included. For custom installations, see the installation guide in the extension documentation.
+
+**Quick enable**
+
+```toml
+[extensions.tn_vacuum]
+enabled = true
+block_interval = 50000  # runs vacuum every 50k blocks
+```
+
+After editing `config.toml`, restart `kwild` for the change to take effect.
+
+For tuning guidance, metrics, and troubleshooting, see the full documentation:
+
+[extensions/tn_vacuum/README.md](../extensions/tn_vacuum/README.md)
+
 ### 7. Become a Validator (Optional)
 
 To upgrade your node to a validator:
@@ -577,19 +597,19 @@ For Ubuntu/Debian:
 
 ```bash
 sudo apt-get update
-sudo apt-get install postgresql-client-16
+sudo apt-get install postgresql-client-16 postgresql-16-repack
 ```
 
 For CentOS/RHEL:
 
 ```bash
-sudo yum install postgresql16
+sudo yum install postgresql16 pg_repack_16
 ```
 
 For macOS (using Homebrew):
 
 ```bash
-brew install postgresql@16
+brew install postgresql@16 pg_repack
 ```
 
 Verify the installation:
@@ -888,7 +908,7 @@ Sometimes you may need to reset your node to sync from a specific point or recov
        -e "POSTGRES_HOST_AUTH_METHOD=trust" \
        -v tn-pgdata:/var/lib/postgresql/data \
        --shm-size=1gb \
-       kwildb/postgres:latest
+      ghcr.io/trufnetwork/kwil-postgres:latest
    ```
 
 8. **Re-enable and start services**:
@@ -985,6 +1005,3 @@ private = true
 ```
 
 For more details, see the [Kwil Private RPC documentation](http://docs.kwil.com/docs/node/private-rpc).
-
-
-

docs/node-upgrade-guide.md

@@ -203,7 +203,7 @@ kwild blacklist list
 ## What About PostgreSQL & Other Components?
 
 *Minor* Kwil releases do **not** require a database upgrade.  
-If the release notes specify a new official Postgres image (e.g. `kwildb/postgres:x.y-z`) you can recreate the container at your convenience – data volumes are preserved.
+If the release notes specify a new official Postgres image (e.g. `ghcr.io/trufnetwork/kwil-postgres:x.y-z`) you can recreate the container at your convenience – data volumes are preserved.
 
 ---
 

extensions/leaderwatch/constants.go

@@ -0,0 +1,3 @@
+package leaderwatch
+
+const ExtensionName = "leaderwatch"