diff options
Diffstat (limited to 'Installation-Notes.md')
| -rw-r--r-- | Installation-Notes.md | 87 |
1 files changed, 47 insertions, 40 deletions
diff --git a/Installation-Notes.md b/Installation-Notes.md index 81c96fe..2f79155 100644 --- a/Installation-Notes.md +++ b/Installation-Notes.md @@ -1,13 +1,14 @@ -The recommended way to run tt-rss is under Docker. +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 -> [!NOTE] -> Podman is not Docker. Please don't report issues when using Podman or podman-compose. +> [!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. We recommend using an external [Patroni cluster](https://patroni.readthedocs.io/en/latest/) instead of a single `db` container in production deployments. +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 @@ -67,15 +68,19 @@ HTTP_PORT=127.0.0.1:8280 ### docker-compose.yml -```yaml -version: '3' +>[!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). -services: +> [!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. - # see FAQ entry below if upgrading from a different PostgreSQL major version (e.g. 12 to 15): - # https://github.com/supahgreg/tt-rss/wiki/Installation-Notes#i-got-the-updated-compose-file-above-and-now-my-database-keeps-restarting +```yaml +services: db: - image: postgres:15-alpine + image: postgres:18-alpine restart: unless-stopped env_file: - .env @@ -84,7 +89,7 @@ services: - POSTGRES_PASSWORD=${TTRSS_DB_PASS} - POSTGRES_DB=${TTRSS_DB_NAME} volumes: - - db:/var/lib/postgresql/data + - db:/var/lib/postgresql app: image: supahgreg/tt-rss:latest @@ -144,12 +149,11 @@ volumes: ### Your Docker images won't run on X! -You might need to build your own Docker images if you're on a platform without "official" images by using an override and running `docker-compose build`. +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 -version: '3' - services: app: image: supahgreg/tt-rss:latest @@ -166,28 +170,32 @@ services: 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. +`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 only). +> 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 -Error message: The data directory was initialized by PostgreSQL version 12, which is not compatible with this version 15.4. +We'll use the following error message as an example of what you might see in the logs: -Official PostgreSQL containers have no support for migrating data between major versions. You can do one of the following: +`Error message: The data directory was initialized by PostgreSQL version 12, which is not compatible with this version 15.4.` -1. Replace `postgres:15-alpine` with `postgres:12-alpine` in the compose file (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 & restore (somewhat complicated if you haven't done it before); +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`. -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). +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). -Either undo your changes or figure how to fix the problem you created and everything should work properly. +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? @@ -220,17 +228,15 @@ Look [here](https://github.com/supahgreg/tt-rss/wiki/Global-Config) for more inf 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 commiting my changes to git? +### 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: +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 -version: '3' - services: db: - image: postgres:12-alpine + image: postgres:18-alpine ``` ### I'm trying to run CLI tt-rss scripts inside the container and they complain about root @@ -265,7 +271,7 @@ Note: `sudo -E` is needed to keep environment variables. > [!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 +By default, tt-rss code is stored on a persistent Docker volume (`app`). You can find its location like this: ```sh @@ -334,7 +340,7 @@ You can but you'll need to pass `APP_UPSTREAM` environment variable to the `web- HTTP_PORT=127.0.0.1:8280 ``` -#### Nginx example +#### nginx example ```nginx location /tt-rss/ { @@ -348,7 +354,7 @@ location /tt-rss/ { } ``` -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: +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/ { @@ -393,7 +399,7 @@ Note that `proxy_pass` in this example points to container website root. ### 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/`. +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: @@ -411,11 +417,12 @@ If your service uses a non-standard (i.e. not 80 or 443) port, make an internal 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. +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 -A process to restore the database from such backup would look like this: +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` @@ -446,17 +453,17 @@ volumes: Don't forget to restart the containers. -### How do I run these images on K8S? +### How do I run these images on Kubernetes? -You'll need to set several mandatory environment values to the container running web-nginx image: +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; +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? +### Where's the Helm chart? -I don't provide one. You will have to make your own. +You'll have to make your own. ### I'm using Podman, and... -I neither test against nor support Podman. Please don't report any issues when using it. +We neither test against nor support Podman. |