more docs

.env.docker

@@ -5,12 +5,20 @@
 # Docker-wide configuration
 ###############################################################
 
-# Path (relative) to the docker-compose file where containers will store their data
+# Path (relative to the docker-compose.yml) or absolute (/some/other/path) file where containers will store their data
 DOCKER_DATA_ROOT="./data"
 
-# Path (relative) to the docker-compose file where containers will store their config
+# Path (relative to the docker-compose.yml) or absolute (/some/other/path) file where containers will store their confguration
 DOCKER_CONFIG_ROOT="./config"
 
+# Image to pull the Pixelfed Docker images from
+#
+# Possible values:
+#   - "ghcr.io/pixelfed/pixelfed" to pull from GitHub
+#   - "pixelfed/pixelfed" to pull from DockerHub
+#
+DOCKER_IMAGE="ghcr.io/jippi/pixelfed"
+
 # Pixelfed version (image tag) to pull from the registry
 DOCKER_TAG="branch-jippi-fork-apache-8.1"
 
@@ -569,7 +577,7 @@ ACTIVITY_PUB="true"
 #MEDIA_DELETE_LOCAL_AFTER_CLOUD="true"
 
 ###############################################################
-# Storage (cloud) - S3
+# Storage (cloud) - S3 andS S3 *compatible* providers (most of them)
 ###############################################################
 
 # See: https://docs.pixelfed.org/technical-documentation/config/#aws_access_key_id
@@ -901,14 +909,6 @@ POSTGRES_DB="${DB_DATABASE}"
 # Docker Specific configuration
 ###############################################################
 
-# Image to pull the Pixelfed Docker images from
-#
-# Possible values:
-#   - "ghcr.io/pixelfed/pixelfed" to pull from GitHub
-#   - "pixelfed/pixelfed" to pull from DockerHub
-#
-DOCKER_IMAGE="ghcr.io/jippi/pixelfed"
-
 # Port that Redis will listen on *outside* the container (e.g. the host machine)
 DOCKER_REDIS_PORT_EXTERNAL="${REDIS_PORT}"
 

docker/README.md

@@ -1,25 +1,103 @@
 # Pixelfed + Docker + Docker Compose
 
+This guide will help you install and run Pixelfed on **your** server using [Docker Compose](https://docs.docker.com/compose/).
+
 ## Prerequisites
 
-* One of the `docker-compose.yml` files in this directory
+Recommendations and requirements for hardware and software needed to run Pixelfed using Docker Compose.
-* A copy of the `example.env` file named `.env` next to `docker-compose.yml`
 
-Your folder should look like this
+It's highly recommended that you have *some* experience with Linux (e.g. Ubuntu or Debian), SSH, and lightweight server administration.
 
-```plain
+### Server
-.
+
-├── .env
+A VPS or dedicated server you can SSH into, for example
-└── docker-compose.yml
+
-```
+* [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.
+
+### Other
+
+* A **Domain** you need a domain (or subdomain) where your Pixelfed server will be running (for example, `pixelfed.social`)
+* (Optional) An **Email/SMTP provider** for sending e-mails to your users, such as e-mail confirmation and notifications.
+* (Optional) 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)
 
-Minimum required settings to change is:
+### Copy the example configuration file
 
-* `APP_NAME`
+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`).
-* `APP_DOMAIN`
+
-* `DB_PASSWORD`
+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, all 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!
 
@@ -28,10 +106,23 @@ 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)
 
-Since the following things are configured for you out of the box:
+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 --tail=100 --follow`.
 
 ## Runtimes