Add in docs/

This commit is contained in:
asonix 2024-01-28 18:21:11 -06:00
parent a4f1a1e843
commit 378bde933e
1 changed files with 188 additions and 0 deletions

docs/ Normal file
View File

@ -0,0 +1,188 @@
# 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.
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.
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'
image: postgres:16-alpine
- "5432:5432"
- PG_DATA=/var/lib/postgresql/data
- POSTGRES_DB=pictrs
- ./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
with a few optional variables for folks who have TLS involved
For a simple self-hosted postgres deployment, the following variables should be set:
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.
> 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
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:
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
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 `` 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.