For the complete documentation index, see llms.txt. This page is also available as Markdown.

Deploy PowerShell Universal with PostgreSQL using Docker Compose

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.

Prerequisites

  • Docker Desktop 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>
  1. In the same folder, create a file named docker-compose.yml with the following content:

    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.

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 and PostgreSQL.

Start the deployment

  1. Open PowerShell and go to the deployment folder:

  2. Download the images:

  3. Start the containers:

  4. Check the status of the containers and follow the PowerShell Universal logs:

  5. After about 30 seconds, open http://localhost:5000 in a browser and complete the first-time setup.

This example serves PowerShell Universal over HTTP. Before giving users access, configure HTTPS, for example with a reverse proxy.

Verify the deployment

Confirm that PowerShell Universal created its tables in PostgreSQL:

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:

Deploy on another server

  1. Install Docker on the target server (see 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.

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:

To restore it:

Remove the deployment

Stop and remove the containers while keeping the data:

See also

Last updated

Was this helpful?