# ![Immich PostgreSQL](<https://daemonless.io/images/logos/immich-postgres.svg>) Immich PostgreSQL

[![Build Status](<https://img.shields.io/github/actions/workflow/status/daemonless/immich-postgres/build.yaml?style=flat-square&amp;label=Build&amp;color=green>)](<https://github.com/daemonless/immich-postgres/actions>) [![Last Commit](<https://img.shields.io/github/last-commit/daemonless/immich-postgres?style=flat-square&amp;label=Last+Commit&amp;color=blue>)](<https://github.com/daemonless/immich-postgres/commits>) [![OCI Pulls](<https://img.shields.io/docker/pulls/daemonless/immich-postgres?style=flat-square&amp;label=OCI+Pulls&amp;color=blue>)](<https://hub.docker.com/r/daemonless/immich-postgres>) [![sysvipc Required](<https://img.shields.io/badge/sysvipc-required-orange?style=flat-square&amp;logo=freebsd&amp;logoColor=white>)](</guides/ocijail-patch/>)

PostgreSQL with pgvector and vectorchord extensions required by Immich for vector similarity search. Defaults to PostgreSQL 14 (:latest), PostgreSQL 18 available as :18.

|  |  |
| --- | --- |
| **Port** | `5432` |
| **Registry** | [`ghcr.io/daemonless/immich-postgres`](<https://github.com/daemonless/immich-postgres/pkgs/container/immich-postgres>) |
| **Daemonless** | [daemonless/immich-postgres](<https://github.com/daemonless/immich-postgres>) |
| **Source** | [immich-app/immich](<https://github.com/immich-app/immich>) |
| **Website** | [immich.app](<https://immich.app/>) |

This image is part of the [Immich Stack](<https://daemonless.io/images/immich>).

**PostgreSQL version:** `:latest` and `:14` use PostgreSQL 14. `:18` uses PostgreSQL 18. New installations should consider `:18`. If you are migrating an existing Immich instance, stay on `:14` — PostgreSQL major version upgrades require a full `pg_dumpall` and restore. The default `:latest` tag will follow whatever version Immich recommends upstream.

PostgreSQL needs System V shared memory, which a jail does not get by default. Create `immich-postgres.conf` alongside `appjail-director.yml`, the same as the Immich stack's `immich-postgres-template.conf` (`allow.sysvipc` alone does nothing on FreeBSD 15; the jail needs its own `sysv*: new` namespaces):

```
exec.start: "/bin/sh /etc/rc"
exec.stop: "/bin/sh /etc/rc.shutdown jail"
sysvmsg: new
sysvsem: new
sysvshm: new
mount.devfs
persist
ip4: inherit
ip6: inherit
```

## Prerequisites

Before deploying, ensure your host environment is ready. See the [Quick Start Guide](<https://daemonless.io/guides/quick-start/index.md>) for host setup instructions, including the security model for host vs. container privileges.

## Deployment

**Customize Paths, UID & Ports**

```
services:
  immich-postgres:
    image: "ghcr.io/daemonless/immich-postgres:latest"
    container_name: immich-postgres
    environment:
      - POSTGRES_USER=postgres  # Database superuser (default: postgres)
      - POSTGRES_PASSWORD=postgres  # Database password (default: postgres)
      - POSTGRES_DB=immich  # Database name (default: immich)
      # - POSTGRES_INITDB_ARGS=  # Additional initdb arguments
    volumes:
      - "/containers/immich-postgres:/var/lib/postgresql/data"
    ports:
      - "5432:5432"
    annotations:
      org.freebsd.jail.allow.sysvipc: "true"
    # always (not unless-stopped) so FreeBSD's podman rc.d auto-starts it at boot
    restart: always
```

Save as `compose.yaml`, then run `podman-compose up -d`.

> [!WARNING]
>
> Exposing ports in AppJail means that your service can be reached from remote hosts. If that is not your intention, do not expose the ports and communicate with the service using the jail's IPv4 address or hostname assigned by the virtual network.

```
# .env

DIRECTOR_PROJECT=immich-postgres
POSTGRES_USER=postgres
POSTGRES_PASSWORD=postgres
POSTGRES_DB=immich
```

```
# appjail-director.yml

options:
  - virtualnet: ':<random> default'
  - nat:
services:
  immich-postgres:
    name: immich_postgres
    options:
      - container: 'args:--pull'
      - expose: '5432:5432 proto:tcp'
      - template: !ENV '${PWD}/immich-postgres.conf'
      - template: !ENV '${PWD}/template.conf'
    oci:
      user: root
      environment:
        - POSTGRES_USER: !ENV '${POSTGRES_USER}'
        - POSTGRES_PASSWORD: !ENV '${POSTGRES_PASSWORD}'
        - POSTGRES_DB: !ENV '${POSTGRES_DB}'
    volumes:
      - immich-postgres: /var/lib/postgresql/data
volumes:
  immich-postgres:
    device: '/containers/immich-postgres'
```

```
# Makejail

ARG tag=latest

OPTION container=boot
OPTION overwrite=force
OPTION from=ghcr.io/daemonless/immich-postgres:${tag}
```

```
# template.conf

exec.start: "/bin/sh /etc/rc"
exec.stop: "/bin/sh /etc/rc.shutdown jail"
mount.devfs
persist
allow.sysvipc
```

Save the files above, then run `appjail-director up`.

> [!WARNING]
>
> **Experimental**
>
> Bastille's OCI support is experimental. It requires `buildah` and shares the host network stack (`inherit`). Mount volumes with `--volume HOST JAIL`; without it, image-declared volumes are stored under `${bastille_volumesdir}/${jail}`.

```
services:
  immich-postgres:
    name: immich-postgres
    image: "ghcr.io/daemonless/immich-postgres:latest"
    network:
      - mode: host
    environment:
      - POSTGRES_USER=postgres
      - POSTGRES_PASSWORD=postgres
      - POSTGRES_DB=immich
    volumes:
      - "/containers/immich-postgres:/var/lib/postgresql/data"
```

Save as `bastille-compose.yml`, then run `bastille up`.

## Parameters

### Environment Variables

| Variable | Default | Description |
| --- | --- | --- |
| `POSTGRES_USER` | `postgres` | Database superuser (default: postgres) |
| `POSTGRES_PASSWORD` | `postgres` | Database password (default: postgres) |
| `POSTGRES_DB` | `immich` | Database name (default: immich) |
| `POSTGRES_INITDB_ARGS` | \`\` | Additional initdb arguments |

### Volumes

| Path | Description |
| --- | --- |
| `/var/lib/postgresql/data` | Database data directory |

### Ports

| Port | Protocol | Description |
| --- | --- | --- |
| `5432` | TCP | PostgreSQL Port |

## Version Tags

Multi-arch manifests — resolve automatically to the right image for your platform.

| Tag | Description | Best For |
| :--- | :--- | :--- |
| `14` / `14-pkg` / `latest` | **Upstream Binary**. Built from official release. | Most users — recommended. |
| `18` / `18-pkg` | **Upstream Binary**. Built from official release. | Alternative build. |

| Tag | Description | Best For |
| :--- | :--- | :--- |
| `14-amd64` / `14-pkg-amd64` / `latest-amd64` | **Upstream Binary**. Built from official release. | Most users — recommended. |
| `18-amd64` / `18-pkg-amd64` | **Upstream Binary**. Built from official release. | Alternative build. |

| Tag | Description | Best For |
| :--- | :--- | :--- |
| `14-aarch64` / `14-pkg-aarch64` / `latest-aarch64` | **Upstream Binary**. Built from official release. | Most users — recommended. |
| `18-aarch64` / `18-pkg-aarch64` | **Upstream Binary**. Built from official release. | Alternative build. |

> [!NOTE]
>
> **Implementation Details**
>
> - **Architectures:** amd64, aarch64
> - **User:** `postgres` (UID/GID set via [PUID/PGID](<https://daemonless.io/guides/permissions/index.md>)). Defaults to `1000:1000`.
> - **Base:** Built on `ghcr.io/daemonless/base` (FreeBSD 15.1).
> - **sysvipc:** Requires `--annotation 'org.freebsd.jail.allow.sysvipc=true'` ([ocijail 0.5.0+](</guides/ocijail-patch/>))

---

Need help? Join our [Discord](<https://discord.gg/Kb9tkhecZT>) community.
