From 2142e8f09745c828b2cfb377c84e5ab2126a1a86 Mon Sep 17 00:00:00 2001 From: supahgreg Date: Mon, 6 Oct 2025 02:44:08 +0000 Subject: Content tweaks and 'Installation Notes' --> 'Installation Guide'. --- FAQ.md | 4 +- Home.md | 4 +- Installation-Guide.md | 469 ++++++++++++++++++++++++++++++++++++++ Installation-Notes.md | 469 -------------------------------------- SSL-Certificate-Authentication.md | 2 +- 5 files changed, 474 insertions(+), 474 deletions(-) create mode 100644 Installation-Guide.md delete mode 100644 Installation-Notes.md diff --git a/FAQ.md b/FAQ.md index 60740f0..68a1699 100644 --- a/FAQ.md +++ b/FAQ.md @@ -1,9 +1,9 @@ > [!NOTE] -> [Docker-related stuff has a separate FAQ page](Installation-Notes#faq) +> [Docker-related stuff is on a separate page](Installation-Guide#faq) ### I want to check how tt-rss renders my feed / the feed I'm trying to use is parsed incorrectly -- tt-rss expects valid XML feed data which is parsed using libxml. Any XML parse errors, should you feel that libxml is misbehaving (which is unlikely), should be reported to libxml developers. We don't add hacks for invalid XML on tt-rss side. +tt-rss expects valid XML feed data which is parsed using libxml. Any XML parse errors, should you feel that libxml is misbehaving (which is unlikely), should be reported to libxml developers. We don't add hacks for invalid XML on tt-rss side. Plugins may affect parsing, consider disabling any plugins before investigating XML-related issues. diff --git a/Home.md b/Home.md index 3454cd9..6e5550f 100644 --- a/Home.md +++ b/Home.md @@ -32,12 +32,12 @@ You will need the following: * A modern web browser. This generally means a recent version of Chrome/Chromium or Firefox. * A system running Docker. -See the [Docker installation guide](Installation-Notes) for detailed instructions. +See [[Installation-Guide]] for detailed instructions. > [!WARNING] > If you choose to run tt-rss without using Docker support might be limited. -> [!INFO] +> [!NOTE] > Tiny Tiny RSS uses a continuous development model based on the `main` branch, which is considered stable. > It's strongly recommended that you remain current-- meaning using either the most recent Docker image(s) or commit on `main`. diff --git a/Installation-Guide.md b/Installation-Guide.md new file mode 100644 index 0000000..2f79155 --- /dev/null +++ b/Installation-Guide.md @@ -0,0 +1,469 @@ +The main (and recommended) way to run tt-rss is under Docker. + +The Docker images related to https://github.com/supahgreg/tt-rss are: +* https://hub.docker.com/r/supahgreg/tt-rss +* https://hub.docker.com/r/supahgreg/tt-rss-web-nginx + +> [!WARNING] +> Podman is not Docker. Please don't report issues related to running tt-rss when using Podman or Podman Compose. + +This setup uses PostgreSQL and runs tt-rss using several containers as outlined below. +Consider using an external [Patroni cluster](https://patroni.readthedocs.io/en/latest/) instead of a single `db` container in "production" deployments. + +## TL;DR + +Place both `.env` and `docker-compose.yml` together in a directory, edit `.env` as you see fit, run `docker compose up -d`. + +### .env + +```ini +# Put any local modifications here. + +# Run FPM 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 on startup, 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 can customize other config.php defines by setting overrides here. +# See tt-rss/.docker/app/Dockerfile for a complete list. + +# You probably shouldn't disable auth_internal unless you know what you're doing. +# TTRSS_PLUGINS=auth_internal,auth_remote +# TTRSS_SINGLE_USER_MODE=true +# TTRSS_SESSION_COOKIE_LIFETIME=2592000 +# TTRSS_FORCE_ARTICLE_PURGE=30 +# ... + +# Bind exposed port to 127.0.0.1 to run behind reverse proxy on the same host. +# If you plan to expose the container, remove "127.0.0.1:". +HTTP_PORT=127.0.0.1:8280 +#HTTP_PORT=8280 +``` + +### docker-compose.yml + +>[!WARNING] +> See [this FAQ entry](#i-got-the-updated-compose-file-above-and-now-my-database-keeps-restarting) +> if you're upgrading between PostgreSQL major versions (e.g. 15 to 18). + +> [!WARNING] +> The PostgreSQL 18 Docker image changed the volume from `/var/lib/postgresql/data` to `/var/lib/postgresql`, +> which is reflected in the example below. +> See https://hub.docker.com/_/postgres and https://github.com/docker-library/postgres/pull/1259 for more info. + +```yaml +services: + db: + image: postgres:18-alpine + restart: unless-stopped + env_file: + - .env + environment: + - POSTGRES_USER=${TTRSS_DB_USER} + - POSTGRES_PASSWORD=${TTRSS_DB_PASS} + - POSTGRES_DB=${TTRSS_DB_NAME} + volumes: + - db:/var/lib/postgresql + + app: + image: supahgreg/tt-rss:latest + 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: supahgreg/tt-rss: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: supahgreg/tt-rss: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: supahgreg/tt-rss-web-nginx:latest + restart: unless-stopped + env_file: + - .env + ports: + - ${HTTP_PORT}:80 + volumes: + - app:/var/www/html:ro + depends_on: + - app + +volumes: + db: + app: + backups: +``` + +## FAQ + +### Your Docker images won't run on X! + +If you're using an OS or architecture that isn't currently supported you'll likely need to +build your own Docker images by using an override and running `docker-compose build`. + +```yaml +# docker-compose.override.yml +services: + app: + image: supahgreg/tt-rss:latest + build: + dockerfile: .docker/app/Dockerfile + context: https://github.com/supahgreg/tt-rss.git + args: + BUILDKIT_CONTEXT_KEEP_GIT_DIR: 1 + + web-nginx: + image: supahgreg/tt-rss-web-nginx:latest + build: + dockerfile: .docker/web-nginx/Dockerfile + context: https://github.com/supahgreg/tt-rss.git +``` + +`BUILDKIT_CONTEXT_KEEP_GIT_DIR` build argument is needed to display tt-rss version info properly. +If that doesn't work for you (no BuildKit?) you'll have to resort to terrible hacks. + +> [!WARNING] +> Self-built images are not necessarily supported (i.e. best effort and/or community support). + +### I got the updated Docker Compose file above and now my database keeps restarting + +We'll use the following error message as an example of what you might see in the logs: + +`Error message: The data directory was initialized by PostgreSQL version 12, which is not compatible with this version 15.4.` + +Official PostgreSQL containers have no support for migrating data between major versions. +Using the aforementioned example, you could do one of the following: + +1. Replace `postgres:15-alpine` with `postgres:12-alpine` in `docker-compose.yml` (or use `docker-compose.override.yml`, see below) and keep using PG 12 +2. Use [this DB container](https://github.com/pgautoupgrade/docker-pgautoupgrade) which would automatically upgrade the database +3. Migrate the data manually using `pg_dump` and `pg_restore` (somewhat complicated if you haven't done it before) + +### 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`. + +Your Docker setup is messed up for some reason, 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). + +Consider undoing any recent changes, looking up error messages, etc. + +### 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://github.com/supahgreg/tt-rss/wiki/Global-Config) 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://github.com/supahgreg/tt-rss/blob/main/.docker/app/Dockerfile). + +### How do I customize the YML without committing 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 +# docker-compose.override.yml +services: + db: + image: postgres:18-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 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? + +> [!NOTE] +> First party plugins can be added using plugin installer in `Preferences` → `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. + +### 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`) and Docker DNS service should be functional. + +Similar issues may be also caused by Docker `iptables` functionality either being disabled or conflicting with `nftables`. + +### I want to rename `app` (FPM) container + +You can but you'll need to pass `APP_UPSTREAM` environment variable to the `web-nginx` container with its new name. + +### 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. +- Upstream address and port are set using `HTTP_PORT` in `.env`: + +```ini +HTTP_PORT=127.0.0.1:8280 +``` + +#### nginx example + +```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 the 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 example + +``` + + + ProxyPreserveHost On + ProxyPass http://localhost:8280/tt-rss + ProxyPassReverse http://localhost:8280/tt-rss + RequestHeader set "X-Forwarded-Proto" expr=%{REQUEST_SCHEME} + + +``` + +### 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. + +### 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. + +#### Restoring backups + +The process to restore the database from a `backups` container backup might 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 +``` + +### 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. + +### How do I run these images on Kubernetes? + +You'll need to set several mandatory environment values to the container running the `web-nginx` image: + +1. `APP_UPSTREAM` should point to the fully-qualified DNS service name provided by the app (FPM) container/pod +2. `RESOLVER` should be set to `kube-dns.kube-system.svc.cluster.local` + +### Where's the Helm chart? + +You'll have to make your own. + +### I'm using Podman, and... + +We neither test against nor support Podman. diff --git a/Installation-Notes.md b/Installation-Notes.md deleted file mode 100644 index 2f79155..0000000 --- a/Installation-Notes.md +++ /dev/null @@ -1,469 +0,0 @@ -The main (and recommended) way to run tt-rss is under Docker. - -The Docker images related to https://github.com/supahgreg/tt-rss are: -* https://hub.docker.com/r/supahgreg/tt-rss -* https://hub.docker.com/r/supahgreg/tt-rss-web-nginx - -> [!WARNING] -> Podman is not Docker. Please don't report issues related to running tt-rss when using Podman or Podman Compose. - -This setup uses PostgreSQL and runs tt-rss using several containers as outlined below. -Consider using an external [Patroni cluster](https://patroni.readthedocs.io/en/latest/) instead of a single `db` container in "production" deployments. - -## TL;DR - -Place both `.env` and `docker-compose.yml` together in a directory, edit `.env` as you see fit, run `docker compose up -d`. - -### .env - -```ini -# Put any local modifications here. - -# Run FPM 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 on startup, 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 can customize other config.php defines by setting overrides here. -# See tt-rss/.docker/app/Dockerfile for a complete list. - -# You probably shouldn't disable auth_internal unless you know what you're doing. -# TTRSS_PLUGINS=auth_internal,auth_remote -# TTRSS_SINGLE_USER_MODE=true -# TTRSS_SESSION_COOKIE_LIFETIME=2592000 -# TTRSS_FORCE_ARTICLE_PURGE=30 -# ... - -# Bind exposed port to 127.0.0.1 to run behind reverse proxy on the same host. -# If you plan to expose the container, remove "127.0.0.1:". -HTTP_PORT=127.0.0.1:8280 -#HTTP_PORT=8280 -``` - -### docker-compose.yml - ->[!WARNING] -> See [this FAQ entry](#i-got-the-updated-compose-file-above-and-now-my-database-keeps-restarting) -> if you're upgrading between PostgreSQL major versions (e.g. 15 to 18). - -> [!WARNING] -> The PostgreSQL 18 Docker image changed the volume from `/var/lib/postgresql/data` to `/var/lib/postgresql`, -> which is reflected in the example below. -> See https://hub.docker.com/_/postgres and https://github.com/docker-library/postgres/pull/1259 for more info. - -```yaml -services: - db: - image: postgres:18-alpine - restart: unless-stopped - env_file: - - .env - environment: - - POSTGRES_USER=${TTRSS_DB_USER} - - POSTGRES_PASSWORD=${TTRSS_DB_PASS} - - POSTGRES_DB=${TTRSS_DB_NAME} - volumes: - - db:/var/lib/postgresql - - app: - image: supahgreg/tt-rss:latest - 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: supahgreg/tt-rss: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: supahgreg/tt-rss: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: supahgreg/tt-rss-web-nginx:latest - restart: unless-stopped - env_file: - - .env - ports: - - ${HTTP_PORT}:80 - volumes: - - app:/var/www/html:ro - depends_on: - - app - -volumes: - db: - app: - backups: -``` - -## FAQ - -### Your Docker images won't run on X! - -If you're using an OS or architecture that isn't currently supported you'll likely need to -build your own Docker images by using an override and running `docker-compose build`. - -```yaml -# docker-compose.override.yml -services: - app: - image: supahgreg/tt-rss:latest - build: - dockerfile: .docker/app/Dockerfile - context: https://github.com/supahgreg/tt-rss.git - args: - BUILDKIT_CONTEXT_KEEP_GIT_DIR: 1 - - web-nginx: - image: supahgreg/tt-rss-web-nginx:latest - build: - dockerfile: .docker/web-nginx/Dockerfile - context: https://github.com/supahgreg/tt-rss.git -``` - -`BUILDKIT_CONTEXT_KEEP_GIT_DIR` build argument is needed to display tt-rss version info properly. -If that doesn't work for you (no BuildKit?) you'll have to resort to terrible hacks. - -> [!WARNING] -> Self-built images are not necessarily supported (i.e. best effort and/or community support). - -### I got the updated Docker Compose file above and now my database keeps restarting - -We'll use the following error message as an example of what you might see in the logs: - -`Error message: The data directory was initialized by PostgreSQL version 12, which is not compatible with this version 15.4.` - -Official PostgreSQL containers have no support for migrating data between major versions. -Using the aforementioned example, you could do one of the following: - -1. Replace `postgres:15-alpine` with `postgres:12-alpine` in `docker-compose.yml` (or use `docker-compose.override.yml`, see below) and keep using PG 12 -2. Use [this DB container](https://github.com/pgautoupgrade/docker-pgautoupgrade) which would automatically upgrade the database -3. Migrate the data manually using `pg_dump` and `pg_restore` (somewhat complicated if you haven't done it before) - -### 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`. - -Your Docker setup is messed up for some reason, 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). - -Consider undoing any recent changes, looking up error messages, etc. - -### 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://github.com/supahgreg/tt-rss/wiki/Global-Config) 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://github.com/supahgreg/tt-rss/blob/main/.docker/app/Dockerfile). - -### How do I customize the YML without committing 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 -# docker-compose.override.yml -services: - db: - image: postgres:18-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 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? - -> [!NOTE] -> First party plugins can be added using plugin installer in `Preferences` → `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. - -### 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`) and Docker DNS service should be functional. - -Similar issues may be also caused by Docker `iptables` functionality either being disabled or conflicting with `nftables`. - -### I want to rename `app` (FPM) container - -You can but you'll need to pass `APP_UPSTREAM` environment variable to the `web-nginx` container with its new name. - -### 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. -- Upstream address and port are set using `HTTP_PORT` in `.env`: - -```ini -HTTP_PORT=127.0.0.1:8280 -``` - -#### nginx example - -```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 the 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 example - -``` - - - ProxyPreserveHost On - ProxyPass http://localhost:8280/tt-rss - ProxyPassReverse http://localhost:8280/tt-rss - RequestHeader set "X-Forwarded-Proto" expr=%{REQUEST_SCHEME} - - -``` - -### 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. - -### 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. - -#### Restoring backups - -The process to restore the database from a `backups` container backup might 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 -``` - -### 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. - -### How do I run these images on Kubernetes? - -You'll need to set several mandatory environment values to the container running the `web-nginx` image: - -1. `APP_UPSTREAM` should point to the fully-qualified DNS service name provided by the app (FPM) container/pod -2. `RESOLVER` should be set to `kube-dns.kube-system.svc.cluster.local` - -### Where's the Helm chart? - -You'll have to make your own. - -### I'm using Podman, and... - -We neither test against nor support Podman. diff --git a/SSL-Certificate-Authentication.md b/SSL-Certificate-Authentication.md index 720b56b..46de926 100644 --- a/SSL-Certificate-Authentication.md +++ b/SSL-Certificate-Authentication.md @@ -1,6 +1,6 @@ > [!WARNING] > This guide is considered legacy and is no longer supported as it is not compatible with the -> [stock Docker Compose](Installation-Notes) setup. Please don't report any issues when +> [stock Docker Compose](Installation-Guide) setup. Please don't report any issues when > trying to DIY this. This article details the steps to enable user authentication with TT-RSS using a client certificate. -- cgit v1.2.3-54-g00ecf