From 669c437e894760fbc7b6eb1c0c0c47a099da183b Mon Sep 17 00:00:00 2001 From: Andrew Dolgov Date: Fri, 12 May 2023 14:05:37 +0000 Subject: [PATCH] Update Home --- Home.md | 671 +++++++++++++++++++++++++++----------------------------- 1 file changed, 329 insertions(+), 342 deletions(-) diff --git a/Home.md b/Home.md index 9287ef4..1e0bb43 100644 --- a/Home.md +++ b/Home.md @@ -1,342 +1,329 @@ -## Installation - -See [README.md](https://git.tt-rss.org/fox/ttrss-docker-compose.git/tree/README.md) - -## 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? - -You can't, not with this particular setup. I wanted to support both sharing a single domain with other applications and running on a dedicated domain. This was the easiest way to implement it. - -Location is entirely cosmetic so I've decided that adding complexity to optionally strip it wasn't worth it. If you disagree and can't stand ``/tt-rss/`` in the URL, you'll have to modify things a bit to get rid of it. - -### 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 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` → `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? - -A common pattern is shared nginx doing SSL termination, etc. Don't forget to pass `X-Forwarded-Proto` to the container if you're using HTTPS, otherwise tt-rss would generate plain HTTP URLs. - -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 (this assumes you're using HTTPS): - -``` -a2enmod proxy -a2enmod proxy_http -``` - -```apache - - ServerName domain.com - - ... - - ProxyPreserveHost On - ProxyRequests Off - - RequestHeader set X-Forwarded-Proto https - - # Server IP + the exposed port of docker container - ProxyPass / http://127.0.0.1:8280/ - ProxyPassReverse / http://127.0.0.1:8280/ - -``` - -You will need to set ``SELF_URL_PATH`` to a correct (i.e. visible from the outside) value in the ``.env`` file. - -### 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 - -### How do I make this work on Raspberry Pi? - -You won't be able to use official Docker Hub images, those are amd64 only. Use dynamic setup (master branch of this repository) instead. +## Installation + +See [README.md](https://git.tt-rss.org/fox/ttrss-docker-compose.git/tree/README.md) + +## 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? + +You can't, not with this particular setup. I wanted to support both sharing a single domain with other applications and running on a dedicated domain. This was the easiest way to implement it. + +Location is entirely cosmetic so I've decided that adding complexity to optionally strip it wasn't worth it. If you disagree and can't stand ``/tt-rss/`` in the URL, you'll have to modify things a bit to get rid of it. + +### 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 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` → `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 + +``` + + + 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. + +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 + +### How do I make this work on Raspberry Pi? + +You won't be able to use official Docker Hub images, those are amd64 only. Use dynamic setup (master branch of this repository) instead.