> For the complete documentation index, see [llms.txt](https://docs.devolutions.net/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.devolutions.net/powershell-universal/getting-started/docker/docker-compose-postgresql.md).

# Deploy PowerShell Universal with PostgreSQL using Docker Compose

Run PowerShell Universal with a PostgreSQL database on Windows using Docker Compose, with health checks, persistent volumes, verification steps, and troubleshooting.

This article shows how to run PowerShell Universal and a PostgreSQL database as two Linux containers on a Windows machine with Docker Compose. PowerShell Universal stores its data in PostgreSQL instead of the default SQLite database, and reaches it by its service name on the Docker network.

For general information about the PowerShell Universal container image, see [Docker](https://docs.devolutions.net/powershell-universal/getting-started/docker.md).

### Prerequisites

* [Docker Desktop](https://docs.docker.com/desktop/setup/install/windows-install/) for Windows running in **Linux containers** mode, or Docker Engine on Linux.
* Docker Compose v2. Run `docker compose version` to confirm it is available.
* At least 2 GB of memory available to Docker.
* Ports `5000` (PowerShell Universal) and `5432` (PostgreSQL) free on the host, or other ports of your choice.

### Create the configuration files

1. Create an empty folder for the deployment, for example `C:\psu`.
2. In that folder, create a file named `.env` with the following content, and replace the value between angle brackets:

   ```
   POSTGRES_PASSWORD=<StrongPostgresPassword>
   ```

{% hint style="warning" %}
The `.env` file contains a password. Restrict access to it and keep it out of version control. Avoid the `$` and `;` characters in the password, since they are interpreted by Docker Compose and by the connection string.
{% endhint %}

3. In the same folder, create a file named `docker-compose.yml` with the following content:

   ```yaml
   services:
     postgres:
       image: postgres:16-alpine
       container_name: psu-postgres
       restart: unless-stopped
       environment:
         POSTGRES_USER: psu
         POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
         POSTGRES_DB: psu
       ports:
         - "5432:5432"
       volumes:
         - pgdata:/var/lib/postgresql/data
       healthcheck:
         test: ["CMD-SHELL", "pg_isready -U psu -d psu"]
         interval: 5s
         timeout: 5s
         retries: 20

     psu:
       image: devolutions/powershell-universal:latest
       container_name: psu-app
       restart: unless-stopped
       ports:
         - "5000:5000"
       volumes:
         - psudata:/data
       environment:
         Plugins__0: PostgreSQL
         Data__ConnectionString: "Host=postgres;Port=5432;Database=psu;Username=psu;Password=${POSTGRES_PASSWORD}"
         Data__RepositoryPath: /data/Repository
       depends_on:
         postgres:
           condition: service_healthy

   volumes:
     pgdata:
     psudata:
   ```

* `Plugins__0: PostgreSQL` enables the PostgreSQL database plugin, and `Data__ConnectionString` points PowerShell Universal to the `postgres` service.
* The health check and `depends_on` make PowerShell Universal wait until PostgreSQL accepts connections. Without them, PowerShell Universal can fail on the first start.
* The `pgdata` volume stores the database, and the `psudata` volume stores the PowerShell Universal repository (scripts, apps, and configuration files).
* Publishing port `5432` is only needed to connect to PostgreSQL from the host, for example with `psql` or pgAdmin. Remove the `ports` entry of the `postgres` service if you do not need it.

{% hint style="info" %}
For production, pin both images to a specific version instead of `latest` or a floating tag. The available tags are listed on Docker Hub for [PowerShell Universal](https://hub.docker.com/r/devolutions/powershell-universal/tags) and [PostgreSQL](https://hub.docker.com/_/postgres/tags).
{% endhint %}

### Start the deployment

1. Open PowerShell and go to the deployment folder:

   ```powershell
   cd C:\psu
   ```
2. Download the images:

   ```powershell
   docker compose pull
   ```
3. Start the containers:

   ```powershell
   docker compose up -d
   ```
4. Check the status of the containers and follow the PowerShell Universal logs:

   ```powershell
   docker compose ps
   docker compose logs -f psu
   ```
5. After about 30 seconds, open `http://localhost:5000` in a browser and complete the first-time setup.

{% hint style="info" %}
This example serves PowerShell Universal over HTTP. Before giving users access, configure HTTPS, for example with a reverse proxy.
{% endhint %}

### Verify the deployment

Confirm that PowerShell Universal created its tables in PostgreSQL:

```powershell
docker exec psu-postgres psql -U psu -d psu -c "\dt"
```

The command lists the PowerShell Universal tables. If it returns `Did not find any relations`, PowerShell Universal has not connected to the database yet; check the logs with `docker compose logs psu`.

To list the active connections from PowerShell Universal:

```powershell
docker exec psu-postgres psql -U psu -d psu -c "SELECT pid, application_name, client_addr, state FROM pg_stat_activity WHERE datname='psu';"
```

### Deploy on another server

1. Install Docker on the target server (see [Prerequisites](#prerequisites)).
2. Copy the `docker-compose.yml` and `.env` files into a new folder. Make sure the files are named exactly `.env` and `docker-compose.yml`, without a hidden `.txt` extension.
3. Run the commands from [Start the deployment](#start-the-deployment).

Depending on the target server:

| Situation                                   | Action                                                                                   |
| ------------------------------------------- | ---------------------------------------------------------------------------------------- |
| Port `5000` or `5432` is already in use     | Change the host port (the left value) in the `ports` entries, for example `"8080:5000"`. |
| Users need to reach it from other computers | Allow the PowerShell Universal host port in the server firewall.                         |
| Several deployments on the same host        | Use one folder per deployment, with different `container_name` values and host ports.    |

### Troubleshooting

| Message in `docker compose logs psu`                               | Solution                                                                                                                                                                                                                                                     |
| ------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `Failed to connect to postgres:5432` with a timeout                | PostgreSQL was not ready. Make sure the `psu` service has `depends_on` with `condition: service_healthy`.                                                                                                                                                    |
| `password authentication failed for user "psu"` (SQLSTATE `28P01`) | The password in the connection string does not match the PostgreSQL password. PostgreSQL only applies `POSTGRES_PASSWORD` the first time the `pgdata` volume is created; if you changed it afterwards, restore the previous password or recreate the volume. |
| `no pg_hba.conf entry for host` (SQLSTATE `28000`)                 | A custom `pg_hba.conf` file rejects the connection. Add a rule allowing the PowerShell Universal container, or use the default configuration.                                                                                                                |
| `sorry, too many clients already` (SQLSTATE `53300`)               | PostgreSQL reached its `max_connections` limit. Increase the limit or reduce other connections to the database.                                                                                                                                              |
| An error stating that the repository path does not exist           | The volume or folder mounted for `Data__RepositoryPath` is missing or not writable. Check the `volumes` entry of the `psu` service.                                                                                                                          |

### Back up the database

Create a backup of the PostgreSQL database and copy it to the host:

```powershell
docker exec psu-postgres pg_dump -U psu -d psu -F c -f /tmp/psu.dump
docker cp psu-postgres:/tmp/psu.dump .\psu.dump
```

To restore it:

```powershell
docker cp .\psu.dump psu-postgres:/tmp/psu.dump
docker exec psu-postgres pg_restore -U psu -d psu --clean --if-exists /tmp/psu.dump
```

### Remove the deployment

Stop and remove the containers while keeping the data:

```powershell
docker compose down
```

{% hint style="danger" %}
The following command also deletes the volumes, including the PostgreSQL database and the PowerShell Universal repository. This cannot be undone.

```powershell
docker compose down -v
```

{% endhint %}

#### See also

* [Docker](https://docs.devolutions.net/powershell-universal/getting-started/docker.md)
* [Upgrade](https://docs.devolutions.net/powershell-universal/getting-started/upgrading.md)
* [Migrate and Restore](https://docs.devolutions.net/powershell-universal/getting-started/migration.md)


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.devolutions.net/powershell-universal/getting-started/docker/docker-compose-postgresql.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
