Content tweaks and 'Installation Notes' --> 'Installation Guide'.

1 files changed, 0 insertions, 469 deletions

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 <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?
-
-> [!NOTE]
-> First party plugins can be added using 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.
-
-### 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
-
-```
-<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.
-
-### 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.