Update InstallationNotes

1 files changed, 469 insertions, 27 deletions

diff --git a/InstallationNotes.md b/InstallationNotes.md
index 741f315..f119680 100644
--- a/InstallationNotes.md
+++ b/InstallationNotes.md
@@ -1,27 +1,469 @@
-% Installation Guide

-

-**As of 2022, I recommend everyone to use Docker Hub images. Those are generated through a proper CI/CD pipeline which involves basic unit tests and static code analysis. This means you're less likely to receive a broken image. You get no such guarantees when using git master branch. You won't be able to easily rollback to an earlier image either.**

-

-Docker(-compose) is the only supported way to deploy tt-rss.

-

-### Static: uses pre-built images provided via Docker Hub ← recommended for users

-

-This seems to be a more commonly used pattern for Docker containers: images (including a snapshot of tt-rss source code) are built automatically on master branch updates and - if build succeeds - pushed to [Docker Hub](https://hub.docker.com/u/cthulhoo). 

-

-This is recommended for users.

-

-→ [Installation guide (static)](https://git.tt-rss.org/fox/ttrss-docker-compose.git/tree/README.md?h=static-dockerhub )

-

-Updates are handled the usual way. Either run `docker-compose pull` etc. when appropriate or use something like [Watchtower](https://github.com/containrrr/watchtower) to apply updates automatically.

-

-### Dynamic: uses git master branch ← for developers

-

-Use this if you want to always run latest tt-rss code and/or don't want to rely on Docker Hub. Also, using dynamic image makes more sense [for development](https://git.tt-rss.org/fox/ttrss-docker-compose.wiki.git/tree/Home.md#how-do-i-use-dynamic-image-for-development).

-

-→ [Installation guide (dynamic)](https://git.tt-rss.org/fox/ttrss-docker-compose.git/tree/README.md)

-

-Updates are applied automatically from git master branch on container restart.

-

-------

-

-See also: [Host installation (not supported)](InstallationNotesHost).

+% Installation Guide
+
+The only supported way to run tt-rss is under Docker. You can use official images off Docker Hub (AMD64 only) or make your own if you're running another architecture or simply want to.
+
+See also: [Host installation (not supported)](InstallationNotesHost).
+
+This setup uses PostgreSQL and runs tt-rss using several containers as outlined below.
+
+## .env
+
+```ini
+# Copy this file to .env before building the container.
+# Put any local modifications here.
+
+# Run under this UID/GID.
+# OWNER_UID=1000
+# OWNER_GID=1000
+
+# FPM settings.
+#PHP_WORKER_MAX_CHILDREN=5
+#PHP_WORKER_MEMORY_LIMIT=256M
+
+# ADMIN_USER_* settings are applied on every startup.
+
+# Set admin user password to this value. If not set, random password will be
+# generated if default password is being used, look for it in the 'app'
+# container logs.
+#ADMIN_USER_PASS=
+
+# Sets admin user access level to this value.
+# Valid values:
+# -2 - forbidden to login
+# -1 - readonly
+#  0 - default user
+# 10 - admin
+#ADMIN_USER_ACCESS_LEVEL=
+
+# Auto create another user (in addition to built-in admin) unless it
+# already exists.
+#AUTO_CREATE_USER=
+#AUTO_CREATE_USER_PASS=
+#AUTO_CREATE_USER_ACCESS_LEVEL=0
+
+# Default database credentials.
+TTRSS_DB_USER=postgres
+TTRSS_DB_NAME=postgres
+TTRSS_DB_PASS=password
+
+# You will likely need to set this to the correct value, see README.md
+# for more information.
+TTRSS_SELF_URL_PATH=http://localhost:8280/tt-rss
+
+# You can customize other config.php defines by setting overrides here.
+# See app/Dockerfile for complete list. Examples:
+# TTRSS_PLUGINS=auth_remote
+# TTRSS_SINGLE_USER_MODE=true
+# TTRSS_SESSION_COOKIE_LIFETIME=2592000
+# TTRSS_FORCE_ARTICLE_PURGE=30
+# etc, etc.
+
+# bind exposed port to 127.0.0.1 by default in case reverse proxy is used.
+# if you plan to run the container standalone and need origin port exposed
+# use next HTTP_PORT definition (or remove "127.0.0.1:").
+HTTP_PORT=127.0.0.1:8280
+#HTTP_PORT=8280
+```
+
+## docker-compose.yml
+
+```yaml
+version: '3'
+
+services:
+  db:
+    image: postgres:15-alpine
+    restart: unless-stopped
+    environment:
+      - POSTGRES_USER=${TTRSS_DB_USER}
+      - POSTGRES_PASSWORD=${TTRSS_DB_PASS}
+      - POSTGRES_DB=${TTRSS_DB_NAME}
+    volumes:
+      - db:/var/lib/postgresql/data
+
+  app:
+    image: cthulhoo/ttrss-fpm-pgsql-static:latest
+    build:
+      dockerfile: .docker/app/Dockerfile
+      context: https://git.tt-rss.org/fox/tt-rss.git
+    restart: unless-stopped
+    env_file:
+      - .env
+    volumes:
+      - app:/var/www/html
+      - ./config.d:/opt/tt-rss/config.d:ro
+    depends_on:
+      - db
+
+#  optional, makes weekly backups of your install
+#  backups:
+#    image: cthulhoo/ttrss-fpm-pgsql-static:latest
+#    restart: unless-stopped
+#    env_file:
+#      - .env
+#    volumes:
+#      - backups:/backups
+#      - app:/var/www/html
+#    depends_on:
+#      - db
+#    command: /opt/tt-rss/dcron.sh -f
+
+  updater:
+    image: cthulhoo/ttrss-fpm-pgsql-static:latest
+    restart: unless-stopped
+    env_file:
+      - .env
+    volumes:
+      - app:/var/www/html
+      - ./config.d:/opt/tt-rss/config.d:ro
+    depends_on:
+      - app
+    command: /opt/tt-rss/updater.sh
+
+  web-nginx:
+    image: cthulhoo/ttrss-web-nginx:latest
+    build:
+      dockerfile: .docker/web-nginx/Dockerfile
+      context: https://git.tt-rss.org/fox/tt-rss.git
+    restart: unless-stopped
+    env_file:
+      - .env
+    ports:
+      - ${HTTP_PORT}:80
+    volumes:
+      - app:/var/www/html:ro
+    depends_on:
+      - app
+
+volumes:
+  db:
+  app:
+  backups:
+```
+
+## FAQ
+
+### I'm using docker-compose.override.yml and now I'm getting schema update (and other) strange issues
+
+Alternatively, you've changed something related to `/var/www/html/tt-rss` in `docker-compose.yml`.
+
+You screwed up your docker setup somehow, so tt-rss can't update itself to the persistent storage location on startup (this is just an example of one issue, there could be many others).
+
+Related threads:
+
+ - https://community.tt-rss.org/t/schema-version-is-wrong-please-upgrade-the-database/5150
+ - https://community.tt-rss.org/t/closed-problem-with-database-schema-update-to-the-latest-version-146-to-145/5138/7?u=fox
+
+Either undo your changes or figure how to fix the problem you created and everything should work properly.
+
+### How do I make it run without /tt-rss/ in the URL, i.e. at website root?
+
+Set the following variables in `.env`:
+
+```ini
+APP_WEB_ROOT=/var/www/html/tt-rss
+APP_BASE=
+```
+
+Don't forget to remove `/tt-rss/` from `TTRSS_SELF_URL_PATH`.
+
+### How do I apply configuration options?
+
+There are two sets of options you can change through the environment - options specific to tt-rss (those are prefixed with `TTRSS_`) and options affecting container behavior.
+
+#### Options specific to tt-rss
+
+For example, to set tt-rss global option `SELF_URL_PATH`, add the following to `.env`:
+
+```ini
+TTRSS_SELF_URL_PATH=http://example.com/tt-rss
+```
+
+Don't use quotes around values. Note the prefix (`TTRSS_`) before the value.
+
+Look [here](https://tt-rss.org/wiki/GlobalConfig) for more information.
+
+#### Container options
+
+Some options, but not all, are mentioned in `.env-dist`. You can see all available options in the Dockerfile:
+
+- https://dev.tt-rss.org/fox/ttrss-docker-compose/src/branch/static-dockerhub/src/app/Dockerfile#L39 (static)
+- https://dev.tt-rss.org/fox/ttrss-docker-compose/src/branch/master/app/Dockerfile#L28 (dynamic)
+
+### How do I customize the YML without commiting my changes to git?
+
+You can use [docker-compose.override.yml](https://docs.docker.com/compose/extends/). For example, customize `db` to use a different postgres image:
+
+```yml
+version: '3'
+
+services:
+  db:
+    image: postgres:13-alpine
+```
+
+### I'm trying to run CLI tt-rss scripts inside the container and they complain about root
+
+(run in the compose script directory)
+
+```sh
+docker-compose exec --user app app php8 /var/www/html/tt-rss/update.php --help
+
+#                           ^   ^ 
+#                           |   | 
+#                           |   +- service (container) name
+#                           +----- run as user
+```
+
+or
+
+```sh
+docker-compose exec app sudo -Eu app php8 /var/www/html/tt-rss/update.php --help
+```
+
+or
+
+```sh
+docker exec -it <container_id> sudo -Eu app php8 /var/www/html/tt-rss/update.php --help
+```
+
+Note: `sudo -E` is needed to keep environment variables.
+
+### How do I add plugins and themes?
+
+For official plugins, you can use plugin installer in `Preferences` &rarr; `Plugins`.
+
+--------
+
+By default, tt-rss code is stored on a persistent docker volume (``app``). You can find
+its location like this:
+
+```sh
+docker volume inspect ttrss-docker_app | grep Mountpoint
+```
+
+Alternatively, you can mount any host directory as ``/var/www/html`` by updating ``docker-compose.yml``, i.e.:
+
+```yml
+volumes:
+      - app:/var/www/html
+```
+
+Replace with:
+
+```yml
+volumes:
+      - /opt/tt-rss:/var/www/html
+```
+
+Copy and/or git clone any third party plugins into ``plugins.local`` as usual.
+
+### How do I use dynamic image for development?
+
+The idea is to map source code someplace more accessible than a docker volume. Example `docker-compose.override.yml`:
+
+```yml
+
+version: '3'
+
+services:
+  app:
+    build:
+      context:
+        ./app
+    volumes:
+      - ./html:/var/www/html
+    env_file:
+      - .env
+
+  updater:
+    build:
+      context:
+        ./app
+    volumes:
+      - ./html:/var/www/html
+    env_file:
+      - .env
+
+  web-nginx:
+    build: ./web-nginx
+    volumes:
+      - ./html:/var/www/html
+    env_file:
+      - .env
+```
+
+Then open `html/tt-rss` in your source code editor of choice. You can enable PHP debugging using `.env`:
+
+```ini
+TTRSS_XDEBUG_ENABLED=yes
+
+#TTRSS_XDEBUG_HOST=
+# defaults to host IP
+
+#TTRSS_XDEBUG_PORT=9000
+```
+
+### I'm running into 502 errors and/or other connectivity issues
+
+First, check that all containers are running:
+
+```
+$ docker-compose ps
+                   Name                                 Command               State           Ports
+------------------------------------------------------------------------------------------------------------
+ttrss-docker-demo_app_1_f49351cb24ed         /bin/sh -c /startup.sh           Up      9000/tcp
+ttrss-docker-demo_backups_1_8d2aa404e31a     /dcron.sh -f                     Up      9000/tcp
+ttrss-docker-demo_db_1_fc1a842fe245          docker-entrypoint.sh postgres    Up      5432/tcp
+ttrss-docker-demo_updater_1_b7fcc8f20419     /updater.sh                      Up      9000/tcp
+ttrss-docker-demo_web-nginx_1_fcef07eb5c55   /docker-entrypoint.sh ngin ...   Up      127.0.0.1:8280->80/tcp
+```
+
+Then, ensure that frontend (`web-nginx` or `web`) container is up and can contact FPM (`app`) container:
+
+```
+$ docker-compose exec web-nginx ping app
+PING app (172.18.0.3): 56 data bytes
+64 bytes from 172.18.0.3: seq=0 ttl=64 time=0.144 ms
+64 bytes from 172.18.0.3: seq=1 ttl=64 time=0.128 ms
+64 bytes from 172.18.0.3: seq=2 ttl=64 time=0.206 ms
+^C
+--- app ping statistics ---
+3 packets transmitted, 3 packets received, 0% packet loss
+round-trip min/avg/max = 0.128/0.159/0.206 ms
+```
+
+Containers communicate via DNS names assigned by Docker based on service names defined in `docker-compose.yml`. This means that services (specifically, `app`) in the YML must not be renamed, and Docker DNS service should be functional.
+
+Similar issues may be also caused by Docker `iptables` functionality either being disabled or conflicting with `nftables`.
+
+### How do I put this container behind a reverse proxy?
+
+- Don't forget to pass `X-Forwarded-Proto` to the container if you're using HTTPS, otherwise tt-rss would generate plain HTTP URLs.
+- You will need to set ``SELF_URL_PATH`` to a correct (i.e. visible from the outside) value in the ``.env`` file.
+- Address and port correspond to `HTTP_PORT` in `.env`, default: 
+
+```ini
+HTTP_PORT=127.0.0.1:8280
+```
+
+##### Nginx:
+
+```nginx
+location /tt-rss/ {
+    proxy_set_header Host $host;
+    proxy_set_header X-Real-IP $remote_addr;
+    proxy_set_header X-Forwarded-For $remote_addr;
+    proxy_set_header X-Forwarded-Proto $scheme;
+
+    proxy_pass http://127.0.0.1:8280/tt-rss/;
+    break;
+}
+```
+
+If you run into problems with global PHP-to-FPM handler taking priority over proxied location, define tt-rss location like this so it takes higher priority:
+
+```nginx
+location ^~ /tt-rss/ {
+   ....
+}
+```
+
+If you want to pass an entire nginx virtual host to tt-rss:
+
+```nginx
+server {
+   server_name rss.example.com;
+   
+   ...
+
+   location / {
+      proxy_set_header Host $host;
+      proxy_set_header X-Real-IP $remote_addr;
+      proxy_set_header X-Forwarded-For $remote_addr;
+      proxy_set_header X-Forwarded-Proto $scheme;
+      
+      proxy_pass http://127.0.0.1:8280/;
+      break;
+   }
+}
+```
+
+Note that `proxy_pass` in this example points to container website root.
+
+##### Apache
+
+```
+<IfModule mod_proxy.c>
+    <Location /tt-rss>
+      ProxyPreserveHost On
+      ProxyPass        http://localhost:8280/tt-rss
+      ProxyPassReverse http://localhost:8280/tt-rss
+      RequestHeader set "X-Forwarded-Proto" expr=%{REQUEST_SCHEME}
+    </Location>
+  </IfModule>
+```
+
+### I have internal web services tt-rss is complaining about (URL is invalid, loopback address, disallowed ports)
+
+Put your local services on the same docker network with tt-rss, then access them by service (= host) names, i.e. `http://rss-bridge/`.
+
+```yml
+services:
+   rss-bridge:
+....
+networks:
+  default:
+    external:
+      name: ttrss-docker_default
+```      
+      
+If your service uses a non-standard (i.e. not 80 or 443) port, make an internal reverse proxy sidecar container for it.
+
+See also:
+
+- https://community.tt-rss.org/t/heads-up-several-vulnerabilities-fixed/3799/
+- https://community.tt-rss.org/t/got-specified-url-seems-to-be-invalid-when-subscribing-to-an-internal-rss-feed/4024
+
+### Backup and restore
+
+If you have `backups` container enabled, stock configuration makes automatic backups (database, local plugins, etc.) once a week to a separate storage volume.
+
+Note that this container is included as a safety net for people who wouldn't bother with backups otherwise. If you value your data, you should invest your time into setting up something like [WAL-G](https://github.com/wal-g/wal-g) instead.
+
+-------------------------
+
+A process to restore the database from such backup would look like this:
+
+1. Enter `backups` container shell: `docker-compose exec backups /bin/sh`
+2. Inside the container, locate and choose the backup file: `ls -t /backups/*.sql.gz`
+3. Clear database (**THIS WOULD DELETE EVERYTHING IN THE DB**): `psql -h db -U $TTRSS_DB_USER $TTRSS_DB_NAME -e -c "drop schema public cascade; create schema public"`
+3. Restore the backup: `zcat /backups/ttrss-backup-yyyymmdd.sql.gz | psql -h db -U $TTRSS_DB_USER $TTRSS_DB_NAME`
+
+Alternatively, if you want to initiate backups from the host, you can use something like this:
+
+```sh
+source .env
+docker-compose exec db /bin/bash \
+  -c "export PGPASSWORD=$TTRSS_DB_PASS \
+  && pg_dump -U $TTRSS_DB_USER $TTRSS_DB_NAME" \
+  | gzip -9 > backup.sql.gz
+```
+
+([source](https://community.tt-rss.org/t/docker-compose-tt-rss/2894/233?u=fox))
+
+### How do I use custom certificates?
+
+You need to mount custom certificates into the *app* and *updater* containers like this:
+
+```yml
+volumes:
+    ....
+    ./ca1.crt:/usr/local/share/ca-certificates/ca1.crt:ro
+    ./ca2.crt:/usr/local/share/ca-certificates/ca2.crt:ro
+    ....
+```
+
+Don't forget to restart the containers.
+
+See also: https://community.tt-rss.org/t/60-ssl-certificate-problem-unable-to-get-local-issuer-certificate/4838/4?u=fox