Steps

To configure PostgreSQL for XWiki using Docker:

1. Make sure you have already installed and configured a servlet container for XWiki (e.g. Tomcat or Jetty), with the XWiki WAR file extracted/deployed.
2. Install Docker.
3. Start a PostgreSQL container configured for XWiki.

   docker run --name xwiki-postgres \
   -e POSTGRES_USER=xwiki \
   -e POSTGRES_PASSWORD=xwiki \
   -e POSTGRES_DB=xwiki \
   -e "POSTGRES_INITDB_ARGS=--encoding=UTF8 --locale-provider=builtin --locale=C.UTF-8" \
   -v postgres-data:/var/lib/postgresql/data \
   -p 5432:5432 \
   -d postgres:17

   Replace postgres:17 with a supported PostgreSQL version. Replace POSTGRES_PASSWORD with a strong password for production environments. The container automatically creates the xwiki database and user on first startup.

4. Download the appropriate PostgreSQL JDBC driver.
5. Copy the JDBC driver JAR into the XWiki web application's WEB-INF/lib directory, the container's common library directory, or TOMCAT_HOME/lib.
6. Edit the WEB-INF/hibernate.cfg.xml file from the expanded XWiki WAR directory.
7. Remove or disable the configuration sections related to other databases.
8. Uncomment the PostgreSQL configuration section.
9. Configure the PostgreSQL connection URL, using localhost if XWiki runs directly on the host, or the PostgreSQL container/service name if XWiki also runs in Docker on a shared network.

   <property name="hibernate.connection.url">jdbc:postgresql://localhost:5432/xwiki</property>

10. Save the configuration changes.
11. Restart XWiki to apply the changes.
12. Open your wiki in a browser. XWiki connects to the PostgreSQL container, creates its tables on first start, and serves the wiki without a database error.

FAQ

Is there another way to get the JDBC driver?

You can also download the JDBC driver directly from the Maven Central Repository and copy the JAR into your container's common lib directory, or in the XWiki webapp (in WEB-INF/lib), or (in TOMCAT_HOME/lib).

Why does the connection URL use localhost, and does that always work?

The -p 5432:5432 flag in the docker run command publishes the PostgreSQL port to the host machine, so localhost only resolves to PostgreSQL when XWiki runs directly on the host (e.g. via Tomcat or Jetty installed locally). If XWiki itself also runs in a Docker container, put both containers on a shared Docker network and reference PostgreSQL by its container or service name instead of localhost.

Should I use Docker Compose for production?

For production setups, consider using Docker Compose to run XWiki and PostgreSQL together in Docker on a shared network. This avoids exposing the database port to the host and simplifies configuration.

How do I remove the container and its data?

Stop and remove the container, then remove the volume:

docker stop xwiki-postgres && docker rm xwiki-postgres
docker volume rm postgres-data

Related

• Configure PostgreSQL Manually.