pict-rs/docs/postgres.md

How to prepare postgres for pict-rs

Preparing postgres

I already have a postgres

If you already have a postgres server, we'll create an additional database in it for pict-rs. First, you'll need to connect to your postgres server as an administrator. The general command should look like the following.

psql -U postgres

postgres here is the name of the administrator role. If your administrator role is named something else (maybe lemmy) then use that instead.

If postgres is running in a docker-compose environment, it might look like this.

sudo docker-compose exec postgres psql -U postgres

note that the first postgres in this command is the docker-compose service, and the second postgres is the name of the database administrator role

Once you have a postgres shell, we'll configure the postgres user and database.

First, create the pictrs user.

CREATE USER pictrs;

Then set the pictrs user's password

\password pictrs -- allows setting the password for the postgres user

Finally, create the pictrs database giving ownership to the pictrs user.

CREATE DATABASE pictrs OWNER pictrs;

The database configuration is now complete.

I don't have a postgres

Postgres can be installed in a variety of ways, but a simple way to do it is with docker-compose, although installing docker and docker-compose is left as an exercise to the reader. An example docker-compose file can be found below.

version: '3.3'

services:
  postgres:
    image: postgres:16-alpine
    ports:
    - "5432:5432"
    environment:
    - PG_DATA=/var/lib/postgresql/data
    - POSTGRES_DB=pictrs
    - POSTGRES_USER=pictrs
    - POSTGRES_PASSWORD=CREATE_YOUR_OWN_PASSWORD
    volumes:
    - ./storage/postgres:/var/lib/postgresql/data

After the file is written, a quick sudo docker-compose up -d should launch the postgres server, making it available on localhost:5432.

Connecting to postgres

pict-rs can be configured to talk to your postgres server a few different ways.

1. environment variables
2. the pict-rs.toml file
3. commandline arguments

In many cases, environment variables will be the easiest.

Environment Variables

The variables you'll need to set are the following

• PICTRS__REPO__TYPE
• PICTRS__REPO__URL

with a few optional variables for folks who have TLS involved

• PICTRS__REPO__USE_TLS
• PICTRS__REPO__CERTIFICATE_FILE

For a simple self-hosted postgres deployment, the following variables should be set:

PICTRS__REPO__TYPE=postgres
PICTRS__REPO__URL=postgres://pictrs:CREATE_YOUR_OWN_PASSWORD@localhost:5432/pictrs

If you're running pict-rs in the same docker-compose file as you are postgres, then change localhost in the above URL to the name of your postgres service, e.g.

- PICTRS__REPO__TYPE=postgres
- PICTRS__REPO__URL=postgres://pictrs:CREATE_YOUR_OWN_PASSWORD@postgres:5432/pictrs

If your postgres is provided by another party, or exists on a different host, then provide the correct hostname or IP address to reach it.

If your postgres supports TLS connections, as might be present in cloud environments, then the following variables should be set.

PICTRS__REPO__USE_TLS=true
PICTRS__REPO__CERTIFICATE_FILE=/path/to/certificate/file.crt

Note that if you provide a path to the certificate file, pict-rs must be able to read that path. This means that if you're running pict-rs in docker, the certificate file needs to be mounted into the container.

pict-rs.toml

The toml configuration can be set pretty easily. The repo section should look like the following

[repo]
type = 'postgres'
url = 'postgres://pictrs:CREATE_YOUR_OWN_PASSWORD@postgres:5432/pictrs'

note that the hostname postgres should be changed to the host that your postgres server is accessible at.

For enabling TLS, the configuration would look like the following:

[repo]
type = 'postgres'
url = 'postgres://pictrs:CREATE_YOUR_OWN_PASSWORD@postgres:5432/pictrs'
use_tls = true
certificate_file = '/path/to/certificate/file.crt'

Commandline arguments

pict-rs can be configured entirely from the commandline. An example invocation could look like the following:

pict-rs run \
    filesytem -p /path/to/files \
    postgres -u 'postgres://pictrs:CREATE_YOUR_OWN_PASSWORD@postgres:5432/pictrs'

with TLS it could look like this:

pict-rs run \
    filesytem -p /path/to/files \
    postgres \
        -u 'postgres://pictrs:CREATE_YOUR_OWN_PASSWORD@postgres:5432/pictrs' \
        -t \
        -c /path/to/certificate/file.crt

Additional comments

When configuring TLS, the certificate_file setting isn't required, however, it is likely it will be used when TLS is enabled. A case when it might not be required is if your postgres publicly accessible on the internet and receives a valid certificate from a trusted certificate authority.

For testing TLS, I've been using certstrap to generate a CA and certificates. I have a script called setup-tls.sh that looks like this:

certstrap init --common-name pictrsCA
certstrap request-cert --common-name postgres --domain localhost
certstrap sign postgres --CA pictrsCA

This genrates a CA and uses that CA to sign a new certificate for localhost. Then I update postgres' pg_hba.conf file to allow connections over TLS:

hostssl all all all cert clientcert=verify-full

Finally, I launch postgres with a custom commandline.

-c "ssl=on" \
-c "ssl_cert_file=/path/to/postgres.crt" \
-c "ssl_key_file=/path/to/postgres.key" \
-c "ssl_ca_file=/path/to/pictrsCA.crt" \
-c "ssl_crl_file=/path/to/pictrsCA.crl"

Alternatively, I could update the postgresql.conf file.

ssl=on
ssl_cert_file=/path/to/postgres.crt
ssl_key_file=/path/to/postgres.key
ssl_ca_file=/path/to/pictrsCA.crt
ssl_crl_file=/path/to/pictrsCA.crl