homelab/active/podman_immich/immich.md

# Podman immich

- [Podman immich](#podman-immich)
  - [Setup immich Project](#setup-immich-project)
  - [Install immich](#install-immich)
    - [Create the immich user](#create-the-immich-user)
    - [Write the immich compose spec](#write-the-immich-compose-spec)
      - [A Note on Volumes](#a-note-on-volumes)
    - [Convert immich compose spec to quadlets](#convert-immich-compose-spec-to-quadlets)
    - [Create any container-mounted directories](#create-any-container-mounted-directories)
    - [Start and enable your systemd quadlet](#start-and-enable-your-systemd-quadlet)
    - [Expose immich](#expose-immich)
      - [firewalld](#firewalld)
  - [Backup immich](#backup-immich)
  - [Upgrade immich](#upgrade-immich)
    - [Upgrade Quadlets](#upgrade-quadlets)
  - [Uninstall](#uninstall)
  - [Notes](#notes)
    - [SELinux](#selinux)

## Setup immich Project

- [x] Copy and rename this folder to active/podman_immich
- [x] Find and replace immich with the name of the service.
- [x] Create the rootless user to run the podman containers
- [ ] Write the compose.yaml spec for your service
- [ ] Convert the compose.yaml spec to a quadlet
- [ ] Install the quadlet on the podman server
- [ ] Expose the quadlet service
- [ ] Install a backup service and timer

## Install immich

### Create the immich user

```bash
# SSH into your podman server as root
useradd immich
loginctl enable-linger $(id -u immich)
systemctl --user --machine=immich@.host enable podman-restart
systemctl --user --machine=immich@.host enable --now podman.socket
mkdir -p /home/immich/.config/containers/systemd
```

### Write the immich compose spec

1. Pull down the immich files

    ```bash
    # Pull the compose file
    wget -O active/podman_immich/compose/compose.yml https://github.com/immich-app/immich/releases/latest/download/docker-compose.yml

    # Pull the .env file
    wget -O active/podman_immich/quadlets/.env https://github.com/immich-app/immich/releases/latest/download/example.env
    ```

2. Edit the compose.yaml. Replace all environment variables with their correct values.
3. Edit the .env file. Make sure to match exactly what is in the compose file.

#### A Note on Volumes

Named volumes are stored at `/home/immich/.local/share/containers/storage/volumes/`.

### Convert immich compose spec to quadlets

Run the following to convert a compose.yaml into the various `.container` files for systemd:

```bash
# Generate the systemd service
podman run \
--security-opt label=disable \
--rm \
-v $(pwd)/active/podman_immich/compose:/compose \
-v $(pwd)/active/podman_immich/quadlets:/quadlets \
quay.io/k9withabone/podlet \
-f /quadlets \
-i \
--overwrite \
compose /compose/compose.yaml

# Copy the files to the server
export PODMAN_SERVER=
scp -r active/podman_immich/quadlets/. $PODMAN_SERVER:/home/immich/.config/containers/systemd/
ssh $PODMAN_SERVER chown -R immich:immich /home/immich/.config/containers/systemd/
```

### Create any container-mounted directories

SSH into your podman server as root:

```bash
machinectl shell immich@
podman unshare
mkdir library postgres model-cache
```

### Start and enable your systemd quadlet

SSH into your podman server as root:

```bash
machinectl shell immich@
systemctl --user daemon-reload
systemctl --user restart immich-server.service immich-machine-learning.service
# Enable auto-update service which will pull new container images automatically every day
systemctl --user enable --now podman-auto-update.timer
```

### Expose immich

1. If you need a domain, follow the [DDNS instructions](/active/podman_ddns/ddns.md#install-a-new-ddns-service)
2. For a web service, follow the [Caddy instructions](/active/podman_caddy/caddy.md#adding-a-new-caddy-record)
3. Finally, follow your OS's guide for opening ports via its firewall service.

#### firewalld

```bash
# command to get current active zone and default zone
firewall-cmd --get-active-zones
firewall-cmd --get-default-zone

# command to open 443 on tcp
firewall-cmd --permanent --zone=<zone> --add-port=443/tcp

# command to open 80 and 443 on tcp and udp
firewall-cmd --permanent --zone=<zone> --add-port={80,443}/{tcp,udp}

# command to list available services and then open http and https
firewall-cmd --get-services
firewall-cmd --permanent --zone=<zone> --add-service={http,https}
```

## Backup immich

Follow the [Borg Backup instructions](/active/systemd_borg/borg.md#set-up-a-client-for-backup)

## Upgrade immich

### Upgrade Quadlets

Upgrades should be a repeat of [writing the compose spec](#convert-immich-compose-spec-to-quadlets) and [installing the quadlets](#start-and-enable-your-systemd-quadlet)

```bash
export PODMAN_SERVER=
scp -r quadlets/. $PODMAN_SERVER$:/home/immich/.config/containers/systemd/
ssh immich systemctl --user daemon-reload
ssh immich systemctl --user restart immich
```

## Uninstall

```bash
# Stop the user's services
systemctl --user disable podman-restart
podman container stop --all
systemctl --user disable --now podman.socket
systemctl --user disable --now podman-auto-update.timer

# Delete the user (this won't delete their home directory)
# userdel might spit out an error like:
# userdel: user immich is currently used by process 591255
# kill those processes and try again
userdel immich
```

## Notes

### SELinux

<https://blog.christophersmart.com/2021/01/31/podman-volumes-and-selinux/>

:z allows a container to share a mounted volume with all other containers.

:Z allows a container to reserve a mounted volume and prevents any other container from accessing.