UA-Fediland/pixelfed
2
0
Fork 0
mirror of https://github.com/pixelfed/pixelfed.git synced 2024-11-25 15:55:22 +00:00
Code Issues Projects Releases Packages Wiki Activity

remove docs

Browse source 
they now live in https://github.com/pixelfed/docs-next/pull/1

and https://jippi.github.io/pixelfed-docs-next/pr-preview/pr-1/running-pixelfed/
This commit is contained in:
Christian Winther 2024-01-18 16:22:26 +00:00
parent f2b28ece6e
commit 2d223d61ed
6 changed files with 1 additions and 847 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

16
docker/README.md
View file

@ -1,17 +1,3 @@
# Pixelfed + Docker + Docker Compose
* [Setting up a new Pixelfed server with Docker Compose](new-server.md)
* [Migrating to the new `docker-compose.yml` setup](migration.md)
* [Frequently Asked Question / FAQ](faq.md)
* [How do I use my own Proxy server?](faq.md#how-do-i-use-my-own-proxy-server)
* [How do I use my own SSL certificate?](faq.md#how-do-i-use-my-own-ssl-certificate)
* [Understanding Pixelfed Container runtimes (Apache, FPM, Nginx + FPM)](runtimes.md)
* [Apache](runtimes.md#apache)
* [FPM](runtimes.md#fpm)
* [Nginx + FPM](runtimes.md#nginx)
* [Customizing Docker image](customizing.md)
* [Running commands on container start](customizing.md#running-commands-on-container-start)
* [Disabling entrypoint or individual scripts](customizing.md#disabling-entrypoint-or-individual-scripts)
* [Templating](customizing.md#templating)
* [Fixing ownership on startup](customizing.md#fixing-ownership-on-startup)
* [Build settings (arguments)](customizing.md#build-settings-arguments)
Please see the [Pixelfed Docs (Next)](https://jippi.github.io/pixelfed-docs-next/pr-preview/pr-1/running-pixelfed/) for current documentation on Docker usage

219
docker/customizing.md
View file

@ -1,219 +0,0 @@
# Customizing your `Dockerfile`
## Running commands on container start
### Description
When a Pixelfed container starts up, the [`ENTRYPOINT`](https://docs.docker.com/engine/reference/builder/#entrypoint) script will
1. Search the `/docker/entrypoint.d/` directory for files and for each file (in lexical order).
1. Check if the file is executable.
1. If the file is *not* executable, print an error and exit the container.
1. If the file has the extension `.envsh` the file will be [sourced](https://superuser.com/a/46146).
1. If the file has the extension `.sh` the file will be run like a normal script.
1. Any other file extension will log a warning and will be ignored.
### Debugging
You can set environment variable `DOCKER_APP_ENTRYPOINT_DEBUG=1` to show verbose output of what each `entrypoint.d` script is doing.
You can also `docker exec` or `docker run` into a container and run `/`
### Included scripts
* `/docker/entrypoint.d/04-defaults.envsh` calculates Docker container environment variables needed for [templating](#templating) configuration files.
* `/docker/entrypoint.d/05-templating.sh` renders [template](#templating) configuration files.
* `/docker/entrypoint.d/10-storage.sh` ensures Pixelfed storage related permissions and commands are run.
* `//docker/entrypoint.d/15-storage-permissions.sh` (optionally) ensures permissions for files are corrected (see [fixing ownership on startup](#fixing-ownership-on-startup))
* `/docker/entrypoint.d/20-horizon.sh` ensures [Laravel Horizon](https://laravel.com/docs/master/horizon) used by Pixelfed is configured
* `/docker/entrypoint.d/30-cache.sh` ensures all Pixelfed caches (router, view, config) is warmed
### Disabling entrypoint or individual scripts
To disable the entire entrypoint you can set the variable `ENTRYPOINT_SKIP=1`.
To disable individual entrypoint scripts you can add the filename to the space (`" "`) separated variable `ENTRYPOINT_SKIP_SCRIPTS`. (example: `ENTRYPOINT_SKIP_SCRIPTS="10-storage.sh 30-cache.sh"`)
## Templating
The Docker container can do some basic templating (more like variable replacement) as part of the entrypoint scripts via [gomplate](https://docs.gomplate.ca/).
Any file put in the `/docker/templates/` directory will be templated and written to the right directory.
### File path examples
1. To template `/usr/local/etc/php/php.ini` in the container put the source file in `/docker/templates/usr/local/etc/php/php.ini`.
1. To template `/a/fantastic/example.txt` in the container put the source file in `/docker/templates/a/fantastic/example.txt`.
1. To template `/some/path/anywhere` in the container put the source file in `/docker/templates/a/fantastic/example.txt`.
### Available variables
Variables available for templating are sourced (in order, so *last* source takes precedence) like this:
1. `env:` in your `docker-compose.yml` or `-e` in your `docker run` / `docker compose run`
1. Any exported variables in `.envsh` files loaded *before* `05-templating.sh` (e.g. any file with `04-`, `03-`, `02-`, `01-` or `00-` prefix)
1. All key/value pairs in `/var/www/.env.docker`
1. All key/value pairs in `/var/www/.env`
### Template guide 101
Please see the [`gomplate` documentation](https://docs.gomplate.ca/) for a more comprehensive overview.
The most frequent use-case you have is likely to print a environment variable (or a default value if it's missing), so this is how to do that:
* `{{ getenv "VAR_NAME" }}` print an environment variable and **fail** if the variable is not set. ([docs](https://docs.gomplate.ca/functions/env/#envgetenv))
* `{{ getenv "VAR_NAME" "default" }}` print an environment variable and print `default` if the variable is not set. ([docs](https://docs.gomplate.ca/functions/env/#envgetenv))
The script will *fail* if you reference a variable that does not exist (and don't have a default value) in a template.
Please see the
* [`gomplate` syntax documentation](https://docs.gomplate.ca/syntax/)
* [`gomplate` functions documentation](https://docs.gomplate.ca/functions/)
## Fixing ownership on startup
You can set the environment variable `DOCKER_APP_ENSURE_OWNERSHIP_PATHS` to a list of paths that should have their `$USER` and `$GROUP` ownership changed to the configured runtime user and group during container bootstrapping.
The variable is a space-delimited list shown below and accepts both relative and absolute paths:
* `DOCKER_APP_ENSURE_OWNERSHIP_PATHS="./storage ./bootstrap"`
* `DOCKER_APP_ENSURE_OWNERSHIP_PATHS="/some/other/folder"`
## Build settings (arguments)
The Pixelfed Dockerfile utilizes [Docker Multi-stage builds](https://docs.docker.com/build/building/multi-stage/) and [Build arguments](https://docs.docker.com/build/guide/build-args/).
Using *build arguments* allow us to create a flexible and more maintainable Dockerfile, supporting [multiple runtimes](runtimes.md) ([FPM](runtimes.md#fpm), [Nginx](runtimes.md#nginx), [Apache + mod_php](runtimes.md#apache)) and end-user flexibility without having to fork or copy the Dockerfile.
*Build arguments* can be configured using `--build-arg 'name=value'` for `docker build`, `docker compose build` and `docker buildx build`. For `docker-compose.yml` the `args` key for [`build`](https://docs.docker.com/compose/compose-file/compose-file-v3/#build) can be used.
### `PHP_VERSION`
The `PHP` version to use when building the runtime container.
Any valid Docker Hub PHP version is acceptable here, as long as it's [published to Docker Hub](https://hub.docker.com/_/php/tags)
**Example values**:
* `8` will use the latest version of PHP 8
* `8.1` will use the latest version of PHP 8.1
* `8.2.14` will use PHP 8.2.14
* `latest` will use whatever is the latest PHP version
**Default value**: `8.1`
### `PHP_PECL_EXTENSIONS`
PECL extensions to install via `pecl install`
Use [PHP_PECL_EXTENSIONS_EXTRA](#php_pecl_extensions_extra) if you want to add *additional* extenstions.
Only change this setting if you want to change the baseline extensions.
See the [`PECL extensions` documentation on Docker Hub](https://hub.docker.com/_/php) for more information.
**Default value**: `imagick redis`
### `PHP_PECL_EXTENSIONS_EXTRA`
Extra PECL extensions (separated by space) to install via `pecl install`
See the [`PECL extensions` documentation on Docker Hub](https://hub.docker.com/_/php) for more information.
**Default value**: `""`
### `PHP_EXTENSIONS`
PHP Extensions to install via `docker-php-ext-install`.
**NOTE:** use [`PHP_EXTENSIONS_EXTRA`](#php_extensions_extra) if you want to add *additional* extensions, only override this if you want to change the baseline extensions.
See the [`How to install more PHP extensions` documentation on Docker Hub](https://hub.docker.com/_/php) for more information
**Default value**: `intl bcmath zip pcntl exif curl gd`
### `PHP_EXTENSIONS_EXTRA`
Extra PHP Extensions (separated by space) to install via `docker-php-ext-install`.
See the [`How to install more PHP extensions` documentation on Docker Hub](https://hub.docker.com/_/php) for more information.
**Default value**: `""`
### `PHP_EXTENSIONS_DATABASE`
PHP database extensions to install.
By default we install both `pgsql` and `mysql` since it's more convinient (and adds very little build time! but can be overwritten here if required.
**Default value**: `pdo_pgsql pdo_mysql pdo_sqlite`
### `COMPOSER_VERSION`
The version of Composer to install.
Please see the [Docker Hub `composer` page](https://hub.docker.com/_/composer) for valid values.
**Default value**: `2.6`
### `APT_PACKAGES_EXTRA`
Extra APT packages (separated by space) that should be installed inside the image by `apt-get install`
**Default value**: `""`
### `NGINX_VERSION`
Version of `nginx` to when targeting [`nginx-runtime`](runtimes.md#nginx).
Please see the [Docker Hub `nginx` page](https://hub.docker.com/_/nginx) for available versions.
**Default value**: `1.25.3`
### `FOREGO_VERSION`
Version of [`forego`](https://github.com/ddollar/forego) to install.
**Default value**: `0.17.2`
### `GOMPLATE_VERSION`
Version of [`goplate`](https://github.com/hairyhenderson/gomplate) to install.
**Default value**: `v3.11.6`
### `DOTENV_LINTER_VERSION`
Version of [`dotenv-linter`](https://github.com/dotenv-linter/dotenv-linter) to install.
**Default value**: `v3.2.0`
### `PHP_BASE_TYPE`
The `PHP` base image layer to use when building the runtime container.
When targeting
* [`apache-runtime`](runtimes.md#apache) use `apache`
* [`fpm-runtime`](runtimes.md#fpm) use `fpm`
* [`nginx-runtime`](runtimes.md#nginx) use `fpm`
**Valid values**:
* `apache`
* `fpm`
* `cli`
**Default value**: `apache`
### `PHP_DEBIAN_RELEASE`
The `Debian` Operation System version to use.
**Valid values**:
* `bullseye`
* `bookworm`
**Default value**: `bullseye`

34
docker/faq.md
View file

@ -1,34 +0,0 @@
# Pixelfed Docker FAQ
## How do I use my own Proxy server?
No problem! All you have to do is:
1. Change the `DOCKER_PROXY_PROFILE` key/value pair in your `.env` file to `"disabled"`.
* This disables the `proxy` *and* `proxy-acme` services in `docker-compose.yml`.
* The setting is near the bottom of the file.
1. Point your proxy upstream to the exposed `web` port (**Default**: `8080`).
* The port is controlled by the `DOCKER_WEB_PORT_EXTERNAL_HTTP` key in `.env`.
* The setting is near the bottom of the file.
1. Run `docker compose up -d --remove-orphans` to apply the configuration
## How do I use my own SSL certificate?
No problem! All you have to do is:
1. Change the `DOCKER_PROXY_ACME_PROFILE` key/value pair in your `.env` file to `"disabled"`.
* This disabled the `proxy-acme` service in `docker-compose.yml`.
* It does *not* disable the `proxy` service.
1. Put your certificates in `${DOCKER_ALL_HOST_CONFIG_ROOT_PATH}/proxy/certs` (e.g. `./docker-compose/config/proxy/certs`)
* You may need to create this folder manually if it does not exists.
* The following files are expected to exist in the directory for the proxy to detect and use them automatically (this is the same directory and file names as LetsEncrypt uses)
1. `${APP_DOMAIN}.cert.pem`
1. `${APP_DOMAIN}.chain.pem`
1. `${APP_DOMAIN}.fullchain.pem`
1. `${APP_DOMAIN}.key.pem`
* See the [`nginx-proxy` configuration file for name patterns](https://github.com/nginx-proxy/nginx-proxy/blob/main/nginx.tmpl#L659-L670)
1. Run `docker compose up -d --remove-orphans` to apply the configuration
## How do I change the container name prefix?
Change the `DOCKER_ALL_CONTAINER_NAME_PREFIX` key/value pair in your `.env` file.

340
docker/migration.md
View file

@ -1,340 +0,0 @@
# Migrating to the new Pixelfed Docker setup
There is [*a lot* of changes](https://github.com/pixelfed/pixelfed/pull/4844) in how Pixelfed Docker/Docker Compose images work - it's a complete rewrite - with a bunch of breaking changes.
## No more anonymous Docker Compose volumes
The old `docker-compose.yml` configuration file [declared four anonymous volumes](https://github.com/pixelfed/pixelfed/blob/b1ff44ca2f75c088a11576fb03b5bad2fbed4d5c/docker-compose.yml#L72-L76) for storing Pixelfed related data within.
These are no longer used, instead favoring a [Docker bind volume](https://docs.docker.com/storage/bind-mounts/) approach where content are stored directly on the server disk, outside
of a Docker volume.
The consequence of this change is that *all* data stored in the - now unsupported - Docker volumes will no longer be accessible by Pixelfed.
* The `db-data` volume *definitely* contain important data - it's your database after all!
* The `app-storage` volume *definitely* contain important data - it's files uploaded to - or seen by - your server!
* The `redis-data` volume *might* contain important data (depending on your configuration)
* The `app-bootstrap` volume does not contain any important data - all of it will be generated automatically in the new setup on startup. We will *not* be migrating this!
### Migrating off anonymous Docker Compose volumes
#### Caveats and warnings
> [!IMPORTANT]
> This is a best-effort guide to help migrate off the old system, the operation is potentially rather complicated (and risky), so please do be careful!
> [!CAUTION]
> ***PLEASE MAKE SURE TO BACKUP YOUR SERVER AND DATA BEFORE ATTEMPTING A MIGRATION***
>
> **YOUR INSTANCE WILL BE *DOWN* WHILE DOING THE MIGRATION, PLEASE PLAN ACCORDINGLY, DEPENDING ON DATA SIZE IT COULD TAKE ANYWHERE FROM 5 *MINUTES* TO 5 *HOURS***
> [!WARNING]
> **It's important to note that this is a *copy* operation - so disk usage will (temporarily) double while you migrate**
> We provide a "migration container" for your convenience that can access both the new and old volumes, allowing you to copy the data into the setup.
#### Step 0) Backup, rollout, and rollback plan
1. Make sure to backup your server (ideally *after* step 1 below has completed, but *before* is better than not at all!)
1. Capture the current Git version / Pixelfed release you are on (e.g. `git --no-pager log -1` outputs the commit reference as the 2nd word in first line)
1. Backup your `.env` file (we will do this in step 3 as well)
1. Backup your `docker-compose.yml` file (`cp docker-compose.yml docker-compose.yml.old`)
1. Read through the *entire* document before starting
#### Step 1) Migrate your ".env" file
The new `.env` file for Docker is a bit different from the old one (many new settings!) so the easiest is to grab the new `.env.docker` file and modify it from scratch again.
```bash
$ cp .env .env.old
$ wget -O .env.new https://raw.githubusercontent.com/pixelfed/pixelfed/dev/.env.docker
```
Then open your old `.env.old` configuration file, and for each of the key/value pairs within it, find and update the key in the new `.env.new` configuration file.
Don't worry though, the file might *look* different (and significantly larger) but it behaves *exactly* the way the old file did, it just has way more options!
> [!TIP]
> Don't worry if a key is missing in `.env.new`, you can add those key/value pairs back to the new file - ideally in the `Other configuration` section near the end of the file - but anywhere *should* be fine.
This is a great time to review your settings and familiarize you with all the new settings.
> [!NOTE]
> In *particular* the following sections
>
> * `PHP configuration` section (near the end of the file) where
> * The `DOCKER_APP_PHP_VERSION` settings controls your PHP version
> * The `PHP_MEMORY_LIMIT` settings controls your PHP memory limit
> * `Docker Specific configuration` section (near the end of the file) where
> * The `DOCKER_ALL_HOST_DATA_ROOT_PATH` setting dictate where the new migrated data will live.
> * The `DOCKER_APP_RUN_ONE_TIME_SETUP_TASKS` controls if the `One time setup tasks` should run or not. We do *not* want this, since your Pixelfed instance already is set up!
> * [Frequently Asked Question / FAQ](faq.md)
> * [How do I use my own Proxy server?](faq.md#how-do-i-use-my-own-proxy-server)
> * [How do I use my own SSL certificate?](faq.md#how-do-i-use-my-own-ssl-certificate)
#### Step 2) Stop all running containers
> [!CAUTION]
> This will take your Pixelfed instance offline
Stop *all* running containers (web, worker, redis, db)
```bash
$ docker compose down
```
#### Step 3) Pull down the new source code
Update your project to the latest release of Pixelfed by running
```bash
$ git pull origin $release
```
> [!NOTE]
> The `$release` can be any valid git reference like `dev`, `staging` or a [tagged release](https://github.com/pixelfed/pixelfed/releases) such as `v0.12.0`.
#### Step 4) Run the migration container
You can access the Docker container with both old and new volumes by running the following command
```bash
$ docker compose -f docker-compose.migrate.yml run migrate bash
```
This will put you in the `/migrate` directory within the container, containing 8 directories like shown here
```plain
|-- app-storage
| |-- new
| `-- old
|-- db-data
| |-- new
| `-- old
`-- redis-data
|-- new
`-- old
```
#### Step 5) Check the folders
##### Old folders
The following commands should all return *SOME* files and data - if they do not - then there might be an issue with the anonymous volume binding.
```bash
$ ls app-storage/old
$ ls db-data/old
$ ls redis-data/old
```
##### New folders
The following commands should all return *NO* files and data - if they contain data - you need to either delete it (backup first!) or skip that migration step.
If you haven't run `docker compose up` since you updated your project in step (2) - they should be empty and good to go.
```bash
$ ls app-storage/new
$ ls db-data/new
$ ls redis-data/new
```
#### Step 6) Copy the data
> [!WARNING]
> This is where we potentially will double your disk usage (temporarily)
Now we will copy the data from the old volumes, to the new ones.
The migration container has [`rsync`](https://www.digitalocean.com/community/tutorials/how-to-use-rsync-to-sync-local-and-remote-directories) installed - which is perfect for that kind of work!
**NOTE** It's important that the "source" (first path in the `rsync` command) has a trailing `/` - otherwise the directory layout will turn out wrong!
**NOTE** Depending on your server, these commands might take some time to finish, each command should provide a progress bar with rough time estimation.
**NOTE** `rsync` should preserve ownership, permissions, and symlinks correctly for you as well for all the files copied.
Lets copy the data by running the following commands:
```bash
$ rsync -avP app-storage/old/ app-storage/new
$ rsync -avP db-data/old/ db-data/new
$ rsync -avP redis-data/old/ redis-data/new
```
#### Step 7) Sanity checking
Lets make sure everything copied over successfully!
Each *new* directory should contain *something* like (but not always exactly) the following - **NO** directory should have a single folder called `old`, if they do, the `rsync` commands above didn't work correctly - and you need to move the content of the `old` folder into the "root" of the `new` folder like shown a bit in the following sections.
The **redis-data/new** directory might also contain a `server.pid`
```bash
$ ls redis-data/new
appendonlydir
```
The **app-storage/new** directory should look *something* like this
```bash
$ ls app-storage/new
app debugbar docker framework logs oauth-private.key oauth-public.key purify
```
The **db-data/new** directory should look *something* like this. There might be a lot of files, or very few files, but there *must* be a `mysql`, `performance_schema`, and `${DB_DATABASE}` (e.g. `pixelfed_prod` directory)
```bash
$ ls db-data/new
aria_log_control ddl_recovery-backup.log ib_buffer_pool ib_logfile0 ibdata1 mariadb_upgrade_info multi-master.info mysql performance_schema pixelfed_prod sys undo001 undo002 undo003
```
If everything looks good, type `exit` to leave exit the migration container
#### Step 8) Starting up the your Pixelfed server again
With all an updated Pixelfed (step 2), updated `.env` file (step 3), migrated data (step 4, 5, 6 and 7) we're ready to start things back up again.
But before we start your Pixelfed server back up again, lets put the new `.env` file we made in step 1 in its right place.
```bash
$ cp .env.new .env
```
##### The Database
First thing we want to try is to start up the database by running the following command and checking the logs
```bash
$ docker compose up -d db
$ docker compose logs --tail 250 --follow db
```
if there are no errors and the server isn't crashing, great! If you have an easy way of connecting to the Database via a GUI or CLI client, do that as well and verify the database and tables are all there.
##### Redis
Next thing we want to try is to start up the Redis server by running the following command and checking the logs
```bash
$ docker compose up -d redis
$ docker compose logs --tail 250 --follow redis
```
if there are no errors and the server isn't crashing, great!
##### Worker
Next thing we want to try is to start up the Worker server by running the following command and checking the logs
```bash
$ docker compose up -d worker
$ docker compose logs --tail 250 --follow worker
```
The container should output a *lot* of logs from the [docker-entrypoint system](customizing.md#running-commands-on-container-start), but *eventually* you should see these messages
* `Configuration complete; ready for start up`
* `Horizon started successfully.`
If you see one or both of those messages, great, the worker seems to be running.
If the worker is crash looping, inspect the logs and try to resolve the issues.
You can consider the following additional steps:
* Enabling `DOCKER_APP_ENTRYPOINT_DEBUG` which will show even more log output to help understand whats going on
* Enabling `DOCKER_APP_ENSURE_OWNERSHIP_PATHS` against the path(s) that might have permission issues
* Fixing permission issues directly on the host since your data should all be in the `${DOCKER_ALL_HOST_DATA_ROOT_PATH}` folder (`./docker-compose-state/data` by default)
##### Web
The final service, `web`, which will bring your site back online! What a journey it has been.
Lets get to it, run these commands to start the `web` service and inspect the logs.
```bash
$ docker compose up -d web
$ docker compose logs --tail 250 --follow web
```
The output should be pretty much identical to that of the `worker`, so please see that section for debugging tips if the container is crash looping.
If the `web` service came online without issues, start the rest of the (optional) services, such as the `proxy`, if enabled, by running
```bash
$ docker compose up -d
$ docker compose logs --tail 250 --follow
```
If you changed anything in the `.env` file while debugging, some containers might restart now, thats perfectly fine.
#### Step 9) Verify
With all services online, it's time to go to your browser and check everything is working
1. Upload and post a picture
1. Comment on a post
1. Like a post
1. Check Horizon (`https://${APP_DOMAIN}/horizon`) for any errors
1. Check the Docker compose logs via `docker compose logs --follow`
If everything looks fine, yay, you made it to the end! Lets do some cleanup
#### Step 10) Final steps + cleanup
With everything working, please take a new snapshot/backup of your server *before* we do any cleanup. A post-migration snapshot is incredibly useful, since it contains both the old and new configuration + data, making any recovery much easier in a rollback scenario later.
Now, with all the data in the new folders, you can delete the old Docker Container volumes (if you want, completely optional)
List all volumes, and give them a look:
```bash
$ docker volume ls
```
The volumes we want to delete *ends* with the volume name (`db-data`, `app-storage`, `redis-data`, and `app-bootstrap`.) but has some prefix in front of them.
Once you have found the volumes in in the list, delete each of them by running:
```bash
$ docker volume rm $volume_name_in_column_two_of_the_output
```
You can also delete the `docker-compose.yml.old` and `.env.old` file since they are no longer needed
```bash
$ rm docker-compose.yml.old
$ rm .env.old
```
### Rollback
Oh no, something went wrong? No worries, we you got backups and a quick way back!
#### Move `docker-compose.yml` back
```bash
$ cp docker-compose.yml docker-compose.yml.new
$ cp docker-compose.yml.old docker-compose.yml
```
#### Move `.env` file back
```bash
$ cp env.old .env
```
#### Go back to old source code version
```bash
$ git checkout $commit_id_from_step_0
```
#### Start things back up
```bash
docker compose up -d
```
#### Verify it worked

145
docker/new-server.md
View file

@ -1,145 +0,0 @@
# New Pixelfed + Docker + Docker Compose server
This guide will help you install and run Pixelfed on **your** server using [Docker Compose](https://docs.docker.com/compose/).
## Prerequisites
Recommendations and requirements for hardware and software needed to run Pixelfed using Docker Compose.
It's highly recommended that you have *some* experience with Linux (e.g. Ubuntu or Debian), SSH, and lightweight server administration.
### Server
A VPS or dedicated server you can SSH into, for example
* [linode.com VPS](https://www.linode.com/)
* [DigitalOcean VPS](https://digitalocean.com/)
* [Hetzner](https://www.hetzner.com/)
### Hardware
Hardware requirements depends on the amount of users you have (or plan to have), and how active they are.
A safe starter/small instance hardware for 25 users and blow are:
* **CPU/vCPU** `2` cores.
* **RAM** `2-4 GB` as your instance grow, memory requirements will increase for the database.
* **Storage** `20-50 GB` HDD is fine, but ideally SSD or NVMe, *especially* for the database.
* **Network** `100 Mbit/s` or faster.
### Domain and DNS
* A **Domain** (or subdomain) is needed for the Pixelfed server (for example, `pixelfed.social` or `pixelfed.mydomain.com`)
* Having the required `A`/`CNAME` DNS records for your domain (above) pointing to your server.
* Typically an `A` record for the root (sometimes shown as `@`) record for `mydomain.com`.
* Possibly an `A` record for `www.` subdomain as well.
### Network
* Port `80` (HTTP) and `443` (HTTPS) ports forwarded to the server.
* Example for Ubuntu using [`ufw`](https://help.ubuntu.com/community/UFW) for port `80`: `ufw allow 80`
* Example for Ubuntu using [`ufw`](https://help.ubuntu.com/community/UFW) for port `443`: `ufw allow 443`
### Optional
* An **Email/SMTP provider** for sending e-mails to your users, such as e-mail confirmation and notifications.
* An **Object Storage** provider for storing all images remotely, rather than locally on your server.
#### E-mail / SMTP provider
**NOTE**: If you don't plan to use en e-mail/SMTP provider, then make sure to set `ENFORCE_EMAIL_VERIFICATION="false"` in your `.env` file!
There are *many* providers out there, with wildly different pricing structures, features, and reliability.
It's beyond the cope of this document to detail which provider to pick, or how to correctly configure them, but some providers that is known to be working well - with generous free tiers and affordable packages - are included for your convince (*in no particular order*) below:
* [Simple Email Service (SES)](https://aws.amazon.com/ses/) by Amazon Web Services (AWS) is pay-as-you-go with a cost of $0.10/1000 emails.
* [Brevo](https://www.brevo.com/) (formerly SendInBlue) has a Free Tier with 300 emails/day.
* [Postmark](https://postmarkapp.com/) has a Free Tier with 100 emails/month.
* [Forward Email](https://forwardemail.net/en/private-business-email?pricing=true) has a $3/mo/domain plan with both sending and receiving included.
* [Mailtrap](https://mailtrap.io/email-sending/) has a 1000 emails/month free-tier (their `Email Sending` product, *not* the `Email Testing` one).
#### Object Storage
**NOTE**: This is *entirely* optional - by default Pixelfed will store all uploads (videos, images, etc.) directly on your servers storage.
> Object storage is a technology that stores and manages data in an unstructured format called objects. Modern organizations create and analyze large volumes of unstructured data such as photos, videos, email, web pages, sensor data, and audio files
>
> -- [*What is object storage?*](https://aws.amazon.com/what-is/object-storage/) by Amazon Web Services
It's beyond the cope of this document to detail which provider to pick, or how to correctly configure them, but some providers that is known to be working well - with generous free tiers and affordable packages - are included for your convince (*in no particular order*) below:
* [R2](https://www.cloudflare.com/developer-platform/r2/) by CloudFlare has cheap storage, free *egress* (e.g. people downloading images) and included (and free) Content Delivery Network (CDN).
* [B2 cloud storage](https://www.backblaze.com/cloud-storage) by Backblaze.
* [Simple Storage Service (S3)](https://aws.amazon.com/s3/) by Amazon Web Services.
### Software
Required software to be installed on your server
* `git` can be installed with `apt-get install git` on Debian/Ubuntu
* `docker` can be installed by [following the official Docker documentation](https://docs.docker.com/engine/install/)
## Getting things ready
Connect via SSH to your server and decide where you want to install Pixelfed.
In this guide I'm going to assume it will be installed at `/data/pixelfed`.
1. **Install required software** as mentioned in the [Software Prerequisites section above](#software)
1. **Create the parent directory** by running `mkdir -p /data`
1. **Clone the Pixelfed repository** by running `git clone https://github.com/pixelfed/pixelfed.git /data/pixelfed`
1. **Change to the Pixelfed directory** by running `cd /data/pixelfed`
## Modifying your settings (`.env` file)
### Copy the example configuration file
Pixelfed contains a default configuration file (`.env.docker`) you should use as a starter, however, before editing anything, make a copy of it and put it in the *right* place (`.env`).
Run the following command to copy the file: `cp .env.docker .env`
### Modifying the configuration file
The configuration file is *quite* long, but the good news is that you can ignore *most* of it, most of the *server-specific* settings are configured for you out of the box.
The minimum required settings you **must** change is:
* (required) `APP_DOMAIN` which is the hostname you plan to run your Pixelfed server on (e.g. `pixelfed.social`) - must **not** include `http://` or a trailing slash (`/`)!
* (required) `DB_PASSWORD` which is the database password, you can use a service like [pwgen.io](https://pwgen.io/en/) to generate a secure one.
* (optional) `ENFORCE_EMAIL_VERIFICATION` should be set to `"false"` if you don't plan to send emails.
* (optional) `MAIL_DRIVER` and related `MAIL_*` settings if you plan to use an [email/SMTP provider](#e-mail--smtp-provider) - See [Email variables documentation](https://docs.pixelfed.org/running-pixelfed/installation/#email-variables).
* (optional) `PF_ENABLE_CLOUD` / `FILESYSTEM_CLOUD` if you plan to use an [Object Storage provider](#object-storage).
See the [`Configure environment variables`](https://docs.pixelfed.org/running-pixelfed/installation/#app-variables) documentation for details!
You need to mainly focus on following sections
* [App variables](https://docs.pixelfed.org/running-pixelfed/installation/#app-variables)
* [Email variables](https://docs.pixelfed.org/running-pixelfed/installation/#email-variables)
You can skip the following sections, since they are already configured/automated for you:
* `Redis`
* `Database` (except for `DB_PASSWORD`)
* `One-time setup tasks`
### Starting the service
With everything in place and (hopefully) well-configured, we can now go ahead and start our services by running
```shell
docker compose up -d
```
This will download all the required Docker images, start the containers, and being the automatic setup.
You can follow the logs by running `docker compose logs` - you might want to scroll to the top to logs from the start.
You can use the CLI flag `--tail=100` to only see the most recent (`100` in this example) log lines for each container.
You can use the CLI flag `--follow` to continue to see log output from the containers.
You can combine `--tail=100` and `--follow` like this `docker compose logs --tail=100 --follow`.
If you only care about specific contaieners, you can add them to the end of the command like this `docker compose logs web worker proxy`.

94
docker/runtimes.md
View file

@ -1,94 +0,0 @@
# Pixelfed Docker container runtimes
The Pixelfed Dockerfile support multiple target *runtimes* ([Apache](#apache), [Nginx + FPM](#nginx), and [fpm](#fpm)).
You can consider a *runtime* target as individual Dockerfiles, but instead, all of them are build from the same optimized Dockerfile, sharing +90% of their configuration and packages.
**If you are unsure of which runtime to choose, please use the [Apache runtime](#apache) it's the most straightforward one and also the default**
## Apache
Building a custom Pixelfed Docker image using Apache + mod_php can be achieved the following way.
### docker build (Apache)
```shell
docker build \
-f contrib/docker/Dockerfile \
--target apache-runtime \
--tag <docker hub user>/<docker hub repo> \
.
```
### docker compose (Apache)
```yaml
version: "3"
services:
app:
build:
context: .
dockerfile: contrib/docker/Dockerfile
target: apache-runtime
```
## Nginx
Building a custom Pixelfed Docker image using nginx + FPM can be achieved the following way.
### docker build (nginx)
```shell
docker build \
-f contrib/docker/Dockerfile \
--target nginx-runtime \
--build-arg 'PHP_BASE_TYPE=fpm' \
--tag <docker hub user>/<docker hub repo> \
.
```
### docker compose (nginx)
```yaml
version: "3"
services:
app:
build:
context: .
dockerfile: contrib/docker/Dockerfile
target: nginx-runtime
args:
PHP_BASE_TYPE: fpm
```
## FPM
Building a custom Pixelfed Docker image using FPM (only) can be achieved the following way.
### docker build (fpm)
```shell
docker build \
-f contrib/docker/Dockerfile \
--target fpm-runtime \
--build-arg 'PHP_BASE_TYPE=fpm' \
--tag <docker hub user>/<docker hub repo> \
.
```
### docker compose (fpm)
```yaml
version: "3"
services:
app:
build:
context: .
dockerfile: contrib/docker/Dockerfile
target: fpm-runtime
args:
PHP_BASE_TYPE: fpm
```