Merge pull request #1902 from FreshRSS/dev1.11.0

FreshRSS 1.11.0

1 files changed, 72 insertions, 18 deletions

diff --git a/Docker/README.md b/Docker/README.md
index ccf4ab3f0..133e7c3b8 100644
--- a/Docker/README.md
+++ b/Docker/README.md
@@ -26,7 +26,7 @@ sudo docker build --tag freshrss/freshrss -f Docker/Dockerfile .
 
 ## Run FreshRSS
 
-Example using SQLite, and exposing FreshRSS on port 8080. You may have to adapt the network parameters to fit your needs.
+Example using SQLite, built-in cron, and exposing FreshRSS on port 8080. You may have to adapt the parameters to fit your needs.
 
 ```sh
 # You can optionally run from the directory containing the FreshRSS source code:
@@ -35,10 +35,11 @@ cd ./FreshRSS/
 # The data will be saved on the host in `./data/`
 mkdir -p ./data/
 
-sudo docker run -dit --restart unless-stopped --log-opt max-size=10m \
-	-v $(pwd)/data:/var/www/FreshRSS/data \
-	-p 8080:80 \
-	--name freshrss freshrss/freshrss
+sudo docker run -d --restart unless-stopped --log-opt max-size=10m \
+  -v $(pwd)/data:/var/www/FreshRSS/data \
+  -e 'CRON_MIN=5,35' \
+  -p 8080:80 \
+  --name freshrss freshrss/freshrss
 ```
 
 ### Examples with external databases
@@ -50,10 +51,11 @@ See https://hub.docker.com/_/mysql/
 
 ```sh
 sudo docker run -d -v /path/to/mysql-data:/var/lib/mysql -e MYSQL_ROOT_PASSWORD=rootpass -e MYSQL_DATABASE=freshrss -e MYSQL_USER=freshrss -e MYSQL_PASSWORD=pass --name mysql mysql
-sudo docker run -dit --restart unless-stopped --log-opt max-size=10m \
-	-v $(pwd)/data:/var/www/FreshRSS/data \
-	--link mysql -p 8080:80 \
-	--name freshrss freshrss/freshrss
+sudo docker run -d --restart unless-stopped --log-opt max-size=10m \
+  -v $(pwd)/data:/var/www/FreshRSS/data \
+  -e 'CRON_MIN=17,47' \
+  --link mysql -p 8080:80 \
+  --name freshrss freshrss/freshrss
 ```
 
 #### PostgreSQL
@@ -61,10 +63,11 @@ See https://hub.docker.com/_/postgres/
 
 ```sh
 sudo docker run -d -v /path/to/pgsql-data:/var/lib/postgresql/data -e POSTGRES_DB=freshrss -e POSTGRES_USER=freshrss -e POSTGRES_PASSWORD=pass --name postgres postgres
-sudo docker run -dit --restart unless-stopped --log-opt max-size=10m \
-	-v $(pwd)/data:/var/www/FreshRSS/data \
-	--link postgres -p 8080:80 \
-	--name freshrss freshrss/freshrss
+sudo docker run -d --restart unless-stopped --log-opt max-size=10m \
+  -v $(pwd)/data:/var/www/FreshRSS/data \
+  -e 'CRON_MIN=23,53' \
+  --link postgres -p 8080:80 \
+  --name freshrss freshrss/freshrss
 ```
 
 ## Update
@@ -72,7 +75,7 @@ sudo docker run -dit --restart unless-stopped --log-opt max-size=10m \
 ```sh
 # Rebuild an image (see build section above) or get a new online version:
 sudo docker pull freshrss/freshrss
-# And then 
+# And then
 sudo docker stop freshrss
 sudo docker rename freshrss freshrss_old
 # See the run section above for the full command
@@ -89,16 +92,50 @@ sudo docker exec --user apache -it freshrss php ./cli/list-users.php
 
 See the [CLI documentation](../cli/) for all the other commands.
 
-### Cron job to refresh feeds
+## Cron job to automatically refresh feeds
+We recommend a refresh rate of about twice per hour (see *WebSub* / *PubSubHubbub* for real-time updates).
+There is no less than 3 options. Pick a single one.
+
+### Option 1) Cron inside the FreshRSS Docker image
+Easiest, built-in solution, also used in the examples above
+(but your Docker instance will have a second process in the background, without monitoring).
+Just pass the environment variable `CRON_MIN` to your `docker run` command,
+containing a valid cron minute definition such as `'13,43'` (recommended) or `'*/20'`.
+Not passing the `CRON_MIN` environment variable – or setting it to empty string – will disable the cron daemon.
+
+```sh
+sudo docker run -d --restart unless-stopped --log-opt max-size=10m \
+  -v $(pwd)/data:/var/www/FreshRSS/data \
+  -e 'CRON_MIN=13,43' \
+  -p 8080:80 \
+  --name freshrss freshrss/freshrss
+```
+
+### Option 2) Cron on the host machine
+Traditional solution.
 Set a cron job up on your host machine, calling the `actualize_script.php` inside the FreshRSS Docker instance.
+Remember not pass the `CRON_MIN` environment variable to your Docker run, to avoid running the built-in cron daemon of option 1.
 
-#### Example on Debian / Ubuntu
-Create `/etc/cron.d/FreshRSS` with:
+Example on Debian / Ubuntu: Create `/etc/cron.d/FreshRSS` with:
 
 ```
 7,37 * * * * root docker exec --user apache -it freshrss php ./app/actualize_script.php > /tmp/FreshRSS.log 2>&1
 ```
 
+### Option 3) Cron as another instance of the same FreshRSS Docker image
+For advanced users. Offers good logging and monitoring with auto-restart on failure.
+Watch out to use the same run parameters than in your main FreshRSS instance, for database, networking, and file system.
+See cron option 1 for customising the cron schedule.
+
+```sh
+sudo docker run -d --restart unless-stopped --log-opt max-size=10m \
+  -v $(pwd)/data:/var/www/FreshRSS/data \
+  -e 'CRON_MIN=17,37' \
+  --name freshrss_cron freshrss/freshrss \
+  crond -f -d 6
+```
+
+
 ## Debugging
 
 ```sh
@@ -115,5 +152,22 @@ ls /var/www/FreshRSS/
 
 ## Deployment in production
 
-Use a reverse proxy on your host server, such as [Træfik](https://traefik.io/) or [nginx](https://docs.nginx.com/nginx/admin-guide/web-server/reverse-proxy/),
+Use a reverse proxy on your host server, such as [Træfik](https://traefik.io/)
+or [nginx](https://docs.nginx.com/nginx/admin-guide/web-server/reverse-proxy/),
 with HTTPS, for instance using [Let’s Encrypt](https://letsencrypt.org/).
+
+### Example with [docker-compose](https://docs.docker.com/compose/)
+
+A [docker-compose.yml](docker-compose.yml) file is given as an example, using PostgreSQL. In order to use it, you have to adapt:
+- In the `postgresql` service:
+	* the `volumes` section. Be careful to keep the path `/var/lib/postgresql/data` for the container. If the path is wrong, you will not get any error but your db will be gone at the next run;
+	* the `POSTGRES_PASSWORD` in the `environment` section;
+- In the `freshrss` service:
+	* the `volumes` section;
+	* options under the `labels` section are specific to [Træfik](https://traefik.io/), a reverse proxy. If you are not using it, feel free to delete this section. If you are using it, adapt accordingly to your config, especially the `traefik.frontend.rule` option.
+	* the `environment` section to adapt the strategy to update feeds.
+
+You can then launch the stack (postgres + freshrss) with:
+```sh
+docker-compose up -d
+```