Skip to content
Klutch.sh Docs

Deploying an XWiki App

Introduction

XWiki is a powerful, extensible enterprise wiki. This guide shows how to containerize XWiki with a Dockerfile, connect it to PostgreSQL, persist attachments, and deploy it to Klutch.sh over HTTP.

Prerequisites

  • GitHub repository containing your Dockerfile.
  • PostgreSQL database (managed or deployed separately).
  • Klutch.sh project ready in klutch.sh/app.

Project structure

.
└── Dockerfile

Sample Dockerfile

FROM xwiki:latest


# Default XWiki port
ENV JETTY_PORT=8080
EXPOSE 8080

Required environment variables

  • DB_HOST – database host
  • DB_PORT – e.g., 5432
  • DB_DATABASE – database name
  • DB_USER
  • DB_PASSWORD
  • JETTY_PORT=8080

Optional environment variables

  • XWIKI_VERSION – pin a version if needed
  • JAVA_OPTIONS – custom JVM flags (e.g., memory tuning)
  • DB_TYPE=postgresql

Persistence

XWiki stores attachments, extensions, and cache on disk:

  • Mount path: /var/lib/xwiki
  • Size: based on expected attachments, pages, and extensions

Networking

  • Protocol: HTTP
  • Internal port: 8080
  • Users reach https://example-app.klutch.sh while Klutch.sh routes to port 8080 inside the container.
Terminal window
curl -I http://localhost:8080

Deployment on Klutch.sh

  1. Push your Dockerfile to GitHub.
  2. In klutch.sh/app, create a new app and select GitHub as the source.
  3. Klutch.sh automatically detects the Dockerfile in the repository root.
  4. Select HTTP traffic and set the internal port to 8080.
  5. Add environment variables for the database (DB_HOST, DB_PORT, DB_DATABASE, DB_USER, DB_PASSWORD) and any JVM tuning. Mark secrets as sensitive.
  6. Attach a persistent volume at /var/lib/xwiki sized for attachments and extensions.
  7. Deploy. After first boot, complete the XWiki setup wizard and create your admin account.

Verification

  • UI: open https://example-app.klutch.sh and confirm the XWiki welcome page appears.

  • Quick check:

    Terminal window
    curl -I https://example-app.klutch.sh

Next steps

  • Configure LDAP/SSO or other auth methods in the admin console.
  • Schedule backups for PostgreSQL and the /var/lib/xwiki volume.
  • Tune JVM options and caching based on your usage.