From 84d0632a2df1cf833610bc8dd45d4808e4a8dc0e Mon Sep 17 00:00:00 2001 From: VirtualTam Date: Sat, 29 Jul 2017 15:26:27 +0200 Subject: docker: remove `dev` image, update documentation Relates to https://github.com/shaarli/Shaarli/issues/843 Changed: - Update Docker image list - Update Docker documentation structure Removed: - Delete Dockerfile and resources for the `dev` image - Cleanup `doc/` resources Signed-off-by: VirtualTam --- doc/Docker.md | 158 --------------------------- doc/REST-API.md | 105 ------------------ doc/Versioning-and-Branches.md | 76 ------------- doc/_Sidebar.md | 39 ------- doc/md/Docker-101.md | 62 ----------- doc/md/Docker-resources.md | 19 ---- doc/md/Reverse-proxy-configuration.md | 6 - doc/md/Shaarli-images.md | 72 ------------ doc/md/docker/docker-101.md | 62 +++++++++++ doc/md/docker/resources.md | 19 ++++ doc/md/docker/reverse-proxy-configuration.md | 6 + doc/md/docker/shaarli-images.md | 71 ++++++++++++ docker/development/Dockerfile | 38 ------- docker/development/IMAGE.md | 10 -- docker/development/nginx.conf | 80 -------------- docker/development/supervised.conf | 13 --- mkdocs.yml | 8 +- 17 files changed, 162 insertions(+), 682 deletions(-) delete mode 100644 doc/Docker.md delete mode 100644 doc/REST-API.md delete mode 100644 doc/Versioning-and-Branches.md delete mode 100644 doc/_Sidebar.md delete mode 100644 doc/md/Docker-101.md delete mode 100644 doc/md/Docker-resources.md delete mode 100644 doc/md/Reverse-proxy-configuration.md delete mode 100644 doc/md/Shaarli-images.md create mode 100644 doc/md/docker/docker-101.md create mode 100644 doc/md/docker/resources.md create mode 100644 doc/md/docker/reverse-proxy-configuration.md create mode 100644 doc/md/docker/shaarli-images.md delete mode 100644 docker/development/Dockerfile delete mode 100644 docker/development/IMAGE.md delete mode 100644 docker/development/nginx.conf delete mode 100644 docker/development/supervised.conf diff --git a/doc/Docker.md b/doc/Docker.md deleted file mode 100644 index a7d2efb5..00000000 --- a/doc/Docker.md +++ /dev/null @@ -1,158 +0,0 @@ -#Docker -- [Docker usage](#docker-usage)[](.html) -- [Get and run a Shaarli image](#get-and-run-a-shaarli-image)[](.html) -- [Resources](#resources)[](.html) - -## Docker usage -### Basics -Install [Docker](https://www.docker.com/), by following the instructions relevant[](.html) -to your OS / distribution, and start the service. - -#### Search an image on [DockerHub](https://hub.docker.com/)[](.html) - -```bash -$ docker search debian - -NAME DESCRIPTION STARS OFFICIAL AUTOMATED -ubuntu Ubuntu is a Debian-based Linux operating s... 2065 [OK][](.html) -debian Debian is a Linux distribution that's comp... 603 [OK][](.html) -google/debian 47 [OK][](.html) -``` - -#### Show available tags for a repository -```bash -$ curl https://index.docker.io/v1/repositories/debian/tags | python -m json.tool - -% Total % Received % Xferd Average Speed Time Time Time Current -Dload Upload Total Spent Left Speed -100 1283 0 1283 0 0 433 0 --:--:-- 0:00:02 --:--:-- 433 -``` - -Sample output: -```json -[[](.html) - { - "layer": "85a02782", - "name": "stretch" - }, - { - "layer": "59abecbc", - "name": "testing" - }, - { - "layer": "bf0fd686", - "name": "unstable" - }, - { - "layer": "60c52dbe", - "name": "wheezy" - }, - { - "layer": "c5b806fe", - "name": "wheezy-backports" - } -] - -``` - -#### Pull an image from DockerHub -```bash -$ docker pull repository[:tag][](.html) - -$ docker pull debian:wheezy -wheezy: Pulling from debian -4c8cbfd2973e: Pull complete -60c52dbe9d91: Pull complete -Digest: sha256:c584131da2ac1948aa3e66468a4424b6aea2f33acba7cec0b631bdb56254c4fe -Status: Downloaded newer image for debian:wheezy -``` - -## Get and run a Shaarli image -### DockerHub repository -The images can be found in the [`shaarli/shaarli`](https://hub.docker.com/r/shaarli/shaarli/)[](.html) -repository. - -### Available image tags -- `latest`: master branch (tarball release) -- `stable`: stable branch (tarball release) -- `dev`: master branch (Git clone) - -All images rely on: -- [Debian 8 Jessie](https://hub.docker.com/_/debian/)[](.html) -- [PHP5-FPM](http://php-fpm.org/)[](.html) -- [Nginx](http://nginx.org/)[](.html) - -### Download from DockerHub -```bash -$ docker pull shaarli/shaarli -latest: Pulling from shaarli/shaarli -32716d9fcddb: Pull complete -84899d045435: Pull complete -4b6ad7444763: Pull complete -e0345ef7a3e0: Pull complete -5c1dd344094f: Pull complete -6422305a200b: Pull complete -7d63f861dbef: Pull complete -3eb97210645c: Pull complete -869319d746ff: Already exists -869319d746ff: Pulling fs layer -902b87aaaec9: Already exists -Digest: sha256:f836b4627b958b3f83f59c332f22f02fcd495ace3056f2be2c4912bd8704cc98 -Status: Downloaded newer image for shaarli/shaarli:latest -``` - -### Create and start a new container from the image -```bash -# map the host's :8000 port to the container's :80 port -$ docker create -p 8000:80 shaarli/shaarli -d40b7af693d678958adedfb88f87d6ea0237186c23de5c4102a55a8fcb499101 - -# launch the container in the background -$ docker start d40b7af693d678958adedfb88f87d6ea0237186c23de5c4102a55a8fcb499101 -d40b7af693d678958adedfb88f87d6ea0237186c23de5c4102a55a8fcb499101 - -# list active containers -$ docker ps -CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES -d40b7af693d6 shaarli/shaarli /usr/bin/supervisor 15 seconds ago Up 4 seconds 0.0.0.0:8000->80/tcp backstabbing_galileo -``` - -### Stop and destroy a container -```bash -$ docker stop backstabbing_galileo # those docker guys are really rude to physicists! -backstabbing_galileo - -# check the container is stopped -$ docker ps -CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES - -# list ALL containers -$ docker ps -a -CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES -d40b7af693d6 shaarli/shaarli /usr/bin/supervisor 5 minutes ago Exited (0) 48 seconds ago backstabbing_galileo - -# destroy the container -$ docker rm backstabbing_galileo # let's put an end to these barbarian practices -backstabbing_galileo - -$ docker ps -a -CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES -``` - -## Resources -### Docker -- [Interactive Docker training portal](https://www.katacoda.com/courses/docker/) on [Katakoda](https://www.katacoda.com/)[](.html) -- [Where are Docker images stored?](http://blog.thoward37.me/articles/where-are-docker-images-stored/)[](.html) -- [Dockerfile reference](https://docs.docker.com/reference/builder/)[](.html) -- [Dockerfile best practices](https://docs.docker.com/articles/dockerfile_best-practices/)[](.html) -- [Volumes](https://docs.docker.com/userguide/dockervolumes/)[](.html) - -### DockerHub -- [Repositories](https://docs.docker.com/userguide/dockerrepos/)[](.html) -- [Teams and organizations](https://docs.docker.com/docker-hub/orgs/)[](.html) -- [GitHub automated build](https://docs.docker.com/docker-hub/github/)[](.html) - -### Service management -- [Using supervisord](https://docs.docker.com/articles/using_supervisord/)[](.html) -- [Nginx in the foreground](http://nginx.org/en/docs/ngx_core_module.html#daemon)[](.html) -- [supervisord](http://supervisord.org/)[](.html) diff --git a/doc/REST-API.md b/doc/REST-API.md deleted file mode 100644 index d7909978..00000000 --- a/doc/REST-API.md +++ /dev/null @@ -1,105 +0,0 @@ -#REST API -## Usage - -See the [REST API documentation](http://shaarli.github.io/api-documentation/).[](.html) - -## Authentication - -All requests to Shaarli's API must include a JWT token to verify their authenticity. - -This token has to be included as an HTTP header called `Authentication: Bearer `. - -JWT resources : - - * [jwt.io](https://jwt.io) (including a list of client per language).[](.html) - * RFC : https://tools.ietf.org/html/rfc7519 - * https://float-middle.com/json-web-tokens-jwt-vs-sessions/ - * HackerNews thread: https://news.ycombinator.com/item?id=11929267 - - -### Shaarli JWT Token - -JWT tokens are composed by three parts, separated by a dot `.` and encoded in base64: - -``` -[header].[payload].[signature][](.html) -``` - -#### Header - -Shaarli only allow one hash algorithm, so the header will always be the same: - -```json -{ - "typ": "JWT", - "alg": "HS512" -} -``` - -Encoded in base64, it gives: - -``` -ewogICAgICAgICJ0eXAiOiAiSldUIiwKICAgICAgICAiYWxnIjogIkhTNTEyIgogICAgfQ== -``` - -#### Payload - -**Validity duration** - -To avoid infinite token validity, JWT tokens must include their creation date in UNIX timestamp format (timezone independant - UTC) under the key `iat` (issued at). This token will be accepted during 9 minutes. - -```json -{ - "iat": 1468663519 -} -``` - -See [RFC reference](https://tools.ietf.org/html/rfc7519#section-4.1.6).[](.html) - - -#### Signature - -The signature authenticate the token validity. It contains the base64 of the header and the body, separated by a dot `.`, hashed in SHA512 with the API secret available in Shaarli administration page. - -Signature example with PHP: - -```php -$content = base64_encode($header) . '.' . base64_encode($payload); -$signature = hash_hmac('sha512', $content, $secret); -``` - - -### Complete example - -#### PHP - -```php -function generateToken($secret) { - $header = base64_encode('{ - "typ": "JWT", - "alg": "HS512" - }'); - $payload = base64_encode('{ - "iat": '. time() .' - }'); - $signature = hash_hmac('sha512', $header .'.'. $payload , $secret); - return $header .'.'. $payload .'.'. $signature; -} - -$secret = 'mysecret'; -$token = generateToken($secret); -echo $token; -``` - -> `ewogICAgICAgICJ0eXAiOiAiSldUIiwKICAgICAgICAiYWxnIjogIkhTNTEyIgogICAgfQ==.ewogICAgICAgICJpYXQiOiAxNDY4NjY3MDQ3CiAgICB9.1d2c54fa947daf594fdbf7591796195652c8bc63bffad7f6a6db2a41c313f495a542cbfb595acade79e83f3810d709b4251d7b940bbc10b531a6e6134af63a68` - -```php -$options = [[](.html) - 'http' => [[](.html) - 'method' => 'GET', - 'jwt' => $token, - ], -]; -$context = stream_context_create($options); -file_get_contents($apiEndpoint, false, $context); -``` diff --git a/doc/Versioning-and-Branches.md b/doc/Versioning-and-Branches.md deleted file mode 100644 index bbc7719e..00000000 --- a/doc/Versioning-and-Branches.md +++ /dev/null @@ -1,76 +0,0 @@ -#Versioning and Branches -[**WORK IN PROGRESS**][](.html) - -It's important to understand how Shaarli branches work, especially if you're maintaining a 3rd party tools for Shaarli (theme, plugin, etc.), to be sure stay compatible. - -## `master` branch - -The `master` branch is the development branch. Any new change MUST go through this branch using Pull Requests. - -Remarks: - - * This branch shouldn't be used for production as it isn't necessary stable. - * 3rd party aren't required to be compatible with the latest changes. - * Official plugins, themes and libraries (contained within Shaarli organization repos) must be compatible with the master branch. - * The version in this branch is always `dev`. - -## `v0.x` branch - -This `v0.x` branch, points to the latest `v0.x.y` release. - -Explanation: - -When a new version is released, it might contains a major bug which isn't detected right away. For example, a new PHP version is released, containing backward compatibility issue which doesn't work with Shaarli. - -In this case, the issue is fixed in the `master` branch, and the fix is backported the to the `v0.x` branch. Then a new release is made from the `v0.x` branch. - -This workflow allow us to fix any major bug detected, without having to release bleeding edge feature too soon. - -## `latest` branch - -This branch point the latest release. It recommended to use it to get the latest tested changes. - -## `stable` branch - -The `stable` branch doesn't contain any major bug, and is one major digit version behind the latest release. - -For example, the current latest release is `v0.8.3`, the stable branch is an alias to the latest `v0.7.x` release. When the `v0.9.0` version will be released, the stable will move to the latest `v0.8.x` release. - -Remarks: - - * Shaarli release pace isn't fast, and the stable branch might be a few months behind the latest release. - -## Releases - -Releases are always made from the latest `v0.x` branch. - -Note that for every release, we manually generate a tarball which contains all Shaarli dependencies, making Shaarli's installation only one step. - -## Advices on 3rd party git repos workflow - -### Versioning - -Any time a new Shaarli release is published, you should publish a new release of your repo if the changes affected you since the latest release (take a look at the [changelog](https://github.com/shaarli/Shaarli/releases) (*Draft* means not released yet) and the commit log (like [`tpl` folder](https://github.com/shaarli/Shaarli/commits/master/tpl/default) for themes)). You can either:[](.html) - - - use the Shaarli version number, with your repo version. For example, if Shaarli `v0.8.3` is released, publish a `v0.8.3-1` release, where `v0.8.3` states Shaarli compatibility and `-1` is your own version digit for the current Shaarli version. - - use your own versioning scheme, and state Shaarli compatibility in the release description. - -Using this, any user will be able to pick the release matching his own Shaarli version. - -### Major bugfix backport releases - -To be able to support backported fixes, it recommended to use our workflow: - -```bash -# In master, fix the major bug -git commit -m "Katastrophe" -git push origin master -# Get your commit hash -git log --format="%H" -n 1 -# Create a new branch from your latest release, let's say v0.8.2-1 (the tag name) -git checkout -b katastrophe v0.8.2-1 -# Backport the fix commit to your brand new branch -git cherry-pick -git push origin katastrophe -# Then you just have to make a new release from the `katastrophe` branch tagged `v0.8.3-1` -``` diff --git a/doc/_Sidebar.md b/doc/_Sidebar.md deleted file mode 100644 index 8df2e565..00000000 --- a/doc/_Sidebar.md +++ /dev/null @@ -1,39 +0,0 @@ -#_Sidebar -- [Home](Home.html) -- Setup - - [Download and Installation](Download-and-Installation.html) - - [Upgrade and migration](Upgrade-and-migration.html) - - [Server requirements](Server-requirements.html) - - [Server configuration](Server-configuration.html) - - [Server security](Server-security.html) - - [Shaarli configuration](Shaarli-configuration.html) - - [Plugins](Plugins.html) -- [Docker](Docker.html) -- [Usage](Usage.html) - - [Sharing button](Sharing-button.html) (bookmarklet) - - [Browsing and Searching](Browsing-and-Searching.html) - - [Firefox share](Firefox-share.html) - - [RSS feeds](RSS-feeds.html) - - [REST API](REST-API.html) -- How To - - [Backup, restore, import and export](Backup,-restore,-import-and-export.html) - - [Copy an existing installation over SSH and serve it locally](Copy-an-existing-installation-over-SSH-and-serve-it-locally.html) - - [Create and serve multiple Shaarlis (farm)](Create-and-serve-multiple-Shaarlis-(farm).html) - - [Download CSS styles from an OPML list](Download-CSS-styles-from-an-OPML-list.html) - - [Datastore hacks](Datastore-hacks.html) -- [Troubleshooting](Troubleshooting.html) -- [Development](Development.html) - - [GnuPG signature](GnuPG-signature.html) - - [Coding guidelines](Coding-guidelines.html) - - [Directory structure](Directory-structure.html) - - [3rd party libraries](3rd-party-libraries.html) - - [Plugin System](Plugin-System.html) - - [Release Shaarli](Release-Shaarli.html) - - [Versioning and Branches](Versioning-and-Branches.html) - - [Security](Security.html) - - [Static analysis](Static-analysis.html) - - [Theming](Theming.html) - - [Unit tests](Unit-tests.html) -- About - - [FAQ](FAQ.html) - - [Community & Related software](Community-&-Related-software.html) diff --git a/doc/md/Docker-101.md b/doc/md/Docker-101.md deleted file mode 100644 index b02dd149..00000000 --- a/doc/md/Docker-101.md +++ /dev/null @@ -1,62 +0,0 @@ -## Basics -Install [Docker](https://www.docker.com/), by following the instructions relevant -to your OS / distribution, and start the service. - -### Search an image on [DockerHub](https://hub.docker.com/) - -```bash -$ docker search debian - -NAME DESCRIPTION STARS OFFICIAL AUTOMATED -ubuntu Ubuntu is a Debian-based Linux operating s... 2065 [OK] -debian Debian is a Linux distribution that's comp... 603 [OK] -google/debian 47 [OK] -``` - -### Show available tags for a repository -```bash -$ curl https://index.docker.io/v1/repositories/debian/tags | python -m json.tool - -% Total % Received % Xferd Average Speed Time Time Time Current -Dload Upload Total Spent Left Speed -100 1283 0 1283 0 0 433 0 --:--:-- 0:00:02 --:--:-- 433 -``` - -Sample output: -```json -[ - { - "layer": "85a02782", - "name": "stretch" - }, - { - "layer": "59abecbc", - "name": "testing" - }, - { - "layer": "bf0fd686", - "name": "unstable" - }, - { - "layer": "60c52dbe", - "name": "wheezy" - }, - { - "layer": "c5b806fe", - "name": "wheezy-backports" - } -] - -``` - -### Pull an image from DockerHub -```bash -$ docker pull repository[:tag] - -$ docker pull debian:wheezy -wheezy: Pulling from debian -4c8cbfd2973e: Pull complete -60c52dbe9d91: Pull complete -Digest: sha256:c584131da2ac1948aa3e66468a4424b6aea2f33acba7cec0b631bdb56254c4fe -Status: Downloaded newer image for debian:wheezy -``` diff --git a/doc/md/Docker-resources.md b/doc/md/Docker-resources.md deleted file mode 100644 index 082d4a46..00000000 --- a/doc/md/Docker-resources.md +++ /dev/null @@ -1,19 +0,0 @@ -### Docker - -- [Interactive Docker training portal](https://www.katacoda.com/courses/docker/) on [Katakoda](https://www.katacoda.com/) -- [Where are Docker images stored?](http://blog.thoward37.me/articles/where-are-docker-images-stored/) -- [Dockerfile reference](https://docs.docker.com/reference/builder/) -- [Dockerfile best practices](https://docs.docker.com/articles/dockerfile_best-practices/) -- [Volumes](https://docs.docker.com/userguide/dockervolumes/) - -### DockerHub - -- [Repositories](https://docs.docker.com/userguide/dockerrepos/) -- [Teams and organizations](https://docs.docker.com/docker-hub/orgs/) -- [GitHub automated build](https://docs.docker.com/docker-hub/github/) - -### Service management - -- [Using supervisord](https://docs.docker.com/articles/using_supervisord/) -- [Nginx in the foreground](http://nginx.org/en/docs/ngx_core_module.html#daemon) -- [supervisord](http://supervisord.org/) diff --git a/doc/md/Reverse-proxy-configuration.md b/doc/md/Reverse-proxy-configuration.md deleted file mode 100644 index 91ffecff..00000000 --- a/doc/md/Reverse-proxy-configuration.md +++ /dev/null @@ -1,6 +0,0 @@ - -TODO, see https://github.com/shaarli/Shaarli/issues/888 - -## HAProxy - -## Nginx diff --git a/doc/md/Shaarli-images.md b/doc/md/Shaarli-images.md deleted file mode 100644 index 25f6cfdd..00000000 --- a/doc/md/Shaarli-images.md +++ /dev/null @@ -1,72 +0,0 @@ -## Get and run a Shaarli image - -### DockerHub repository -The images can be found in the [`shaarli/shaarli`](https://hub.docker.com/r/shaarli/shaarli/) -repository. - -### Available image tags -- `latest`: master branch (tarball release) -- `stable`: stable branch (tarball release) -- `dev`: master branch (Git clone) - -All images rely on: -- [Debian 8 Jessie](https://hub.docker.com/_/debian/) -- [PHP5-FPM](http://php-fpm.org/) -- [Nginx](http://nginx.org/) - -### Download from DockerHub -```bash -$ docker pull shaarli/shaarli -latest: Pulling from shaarli/shaarli -32716d9fcddb: Pull complete -84899d045435: Pull complete -4b6ad7444763: Pull complete -e0345ef7a3e0: Pull complete -5c1dd344094f: Pull complete -6422305a200b: Pull complete -7d63f861dbef: Pull complete -3eb97210645c: Pull complete -869319d746ff: Already exists -869319d746ff: Pulling fs layer -902b87aaaec9: Already exists -Digest: sha256:f836b4627b958b3f83f59c332f22f02fcd495ace3056f2be2c4912bd8704cc98 -Status: Downloaded newer image for shaarli/shaarli:latest -``` - -### Create and start a new container from the image -```bash -# map the host's :8000 port to the container's :80 port -$ docker create -p 8000:80 shaarli/shaarli -d40b7af693d678958adedfb88f87d6ea0237186c23de5c4102a55a8fcb499101 - -# launch the container in the background -$ docker start d40b7af693d678958adedfb88f87d6ea0237186c23de5c4102a55a8fcb499101 -d40b7af693d678958adedfb88f87d6ea0237186c23de5c4102a55a8fcb499101 - -# list active containers -$ docker ps -CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES -d40b7af693d6 shaarli/shaarli /usr/bin/supervisor 15 seconds ago Up 4 seconds 0.0.0.0:8000->80/tcp backstabbing_galileo -``` - -### Stop and destroy a container -```bash -$ docker stop backstabbing_galileo # those docker guys are really rude to physicists! -backstabbing_galileo - -# check the container is stopped -$ docker ps -CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES - -# list ALL containers -$ docker ps -a -CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES -d40b7af693d6 shaarli/shaarli /usr/bin/supervisor 5 minutes ago Exited (0) 48 seconds ago backstabbing_galileo - -# destroy the container -$ docker rm backstabbing_galileo # let's put an end to these barbarian practices -backstabbing_galileo - -$ docker ps -a -CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES -``` diff --git a/doc/md/docker/docker-101.md b/doc/md/docker/docker-101.md new file mode 100644 index 00000000..b02dd149 --- /dev/null +++ b/doc/md/docker/docker-101.md @@ -0,0 +1,62 @@ +## Basics +Install [Docker](https://www.docker.com/), by following the instructions relevant +to your OS / distribution, and start the service. + +### Search an image on [DockerHub](https://hub.docker.com/) + +```bash +$ docker search debian + +NAME DESCRIPTION STARS OFFICIAL AUTOMATED +ubuntu Ubuntu is a Debian-based Linux operating s... 2065 [OK] +debian Debian is a Linux distribution that's comp... 603 [OK] +google/debian 47 [OK] +``` + +### Show available tags for a repository +```bash +$ curl https://index.docker.io/v1/repositories/debian/tags | python -m json.tool + +% Total % Received % Xferd Average Speed Time Time Time Current +Dload Upload Total Spent Left Speed +100 1283 0 1283 0 0 433 0 --:--:-- 0:00:02 --:--:-- 433 +``` + +Sample output: +```json +[ + { + "layer": "85a02782", + "name": "stretch" + }, + { + "layer": "59abecbc", + "name": "testing" + }, + { + "layer": "bf0fd686", + "name": "unstable" + }, + { + "layer": "60c52dbe", + "name": "wheezy" + }, + { + "layer": "c5b806fe", + "name": "wheezy-backports" + } +] + +``` + +### Pull an image from DockerHub +```bash +$ docker pull repository[:tag] + +$ docker pull debian:wheezy +wheezy: Pulling from debian +4c8cbfd2973e: Pull complete +60c52dbe9d91: Pull complete +Digest: sha256:c584131da2ac1948aa3e66468a4424b6aea2f33acba7cec0b631bdb56254c4fe +Status: Downloaded newer image for debian:wheezy +``` diff --git a/doc/md/docker/resources.md b/doc/md/docker/resources.md new file mode 100644 index 00000000..082d4a46 --- /dev/null +++ b/doc/md/docker/resources.md @@ -0,0 +1,19 @@ +### Docker + +- [Interactive Docker training portal](https://www.katacoda.com/courses/docker/) on [Katakoda](https://www.katacoda.com/) +- [Where are Docker images stored?](http://blog.thoward37.me/articles/where-are-docker-images-stored/) +- [Dockerfile reference](https://docs.docker.com/reference/builder/) +- [Dockerfile best practices](https://docs.docker.com/articles/dockerfile_best-practices/) +- [Volumes](https://docs.docker.com/userguide/dockervolumes/) + +### DockerHub + +- [Repositories](https://docs.docker.com/userguide/dockerrepos/) +- [Teams and organizations](https://docs.docker.com/docker-hub/orgs/) +- [GitHub automated build](https://docs.docker.com/docker-hub/github/) + +### Service management + +- [Using supervisord](https://docs.docker.com/articles/using_supervisord/) +- [Nginx in the foreground](http://nginx.org/en/docs/ngx_core_module.html#daemon) +- [supervisord](http://supervisord.org/) diff --git a/doc/md/docker/reverse-proxy-configuration.md b/doc/md/docker/reverse-proxy-configuration.md new file mode 100644 index 00000000..91ffecff --- /dev/null +++ b/doc/md/docker/reverse-proxy-configuration.md @@ -0,0 +1,6 @@ + +TODO, see https://github.com/shaarli/Shaarli/issues/888 + +## HAProxy + +## Nginx diff --git a/doc/md/docker/shaarli-images.md b/doc/md/docker/shaarli-images.md new file mode 100644 index 00000000..6d108d21 --- /dev/null +++ b/doc/md/docker/shaarli-images.md @@ -0,0 +1,71 @@ +## Get and run a Shaarli image + +### DockerHub repository +The images can be found in the [`shaarli/shaarli`](https://hub.docker.com/r/shaarli/shaarli/) +repository. + +### Available image tags +- `latest`: master branch (tarball release) +- `stable`: stable branch (tarball release) + +All images rely on: +- [Debian 8 Jessie](https://hub.docker.com/_/debian/) +- [PHP5-FPM](http://php-fpm.org/) +- [Nginx](http://nginx.org/) + +### Download from DockerHub +```bash +$ docker pull shaarli/shaarli +latest: Pulling from shaarli/shaarli +32716d9fcddb: Pull complete +84899d045435: Pull complete +4b6ad7444763: Pull complete +e0345ef7a3e0: Pull complete +5c1dd344094f: Pull complete +6422305a200b: Pull complete +7d63f861dbef: Pull complete +3eb97210645c: Pull complete +869319d746ff: Already exists +869319d746ff: Pulling fs layer +902b87aaaec9: Already exists +Digest: sha256:f836b4627b958b3f83f59c332f22f02fcd495ace3056f2be2c4912bd8704cc98 +Status: Downloaded newer image for shaarli/shaarli:latest +``` + +### Create and start a new container from the image +```bash +# map the host's :8000 port to the container's :80 port +$ docker create -p 8000:80 shaarli/shaarli +d40b7af693d678958adedfb88f87d6ea0237186c23de5c4102a55a8fcb499101 + +# launch the container in the background +$ docker start d40b7af693d678958adedfb88f87d6ea0237186c23de5c4102a55a8fcb499101 +d40b7af693d678958adedfb88f87d6ea0237186c23de5c4102a55a8fcb499101 + +# list active containers +$ docker ps +CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES +d40b7af693d6 shaarli/shaarli /usr/bin/supervisor 15 seconds ago Up 4 seconds 0.0.0.0:8000->80/tcp backstabbing_galileo +``` + +### Stop and destroy a container +```bash +$ docker stop backstabbing_galileo # those docker guys are really rude to physicists! +backstabbing_galileo + +# check the container is stopped +$ docker ps +CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES + +# list ALL containers +$ docker ps -a +CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES +d40b7af693d6 shaarli/shaarli /usr/bin/supervisor 5 minutes ago Exited (0) 48 seconds ago backstabbing_galileo + +# destroy the container +$ docker rm backstabbing_galileo # let's put an end to these barbarian practices +backstabbing_galileo + +$ docker ps -a +CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES +``` diff --git a/docker/development/Dockerfile b/docker/development/Dockerfile deleted file mode 100644 index d9ef8da7..00000000 --- a/docker/development/Dockerfile +++ /dev/null @@ -1,38 +0,0 @@ -FROM debian:jessie -MAINTAINER Shaarli Community - -ENV TERM dumb -RUN apt-get update \ - && apt-get install --no-install-recommends -y \ - ca-certificates \ - nginx-light \ - php5-curl \ - php5-fpm \ - php5-gd \ - php5-intl \ - supervisor \ - git \ - nano \ - && apt-get clean - -RUN sed -i 's/post_max_size.*/post_max_size = 10M/' /etc/php5/fpm/php.ini -RUN sed -i 's/upload_max_filesize.*/upload_max_filesize = 10M/' /etc/php5/fpm/php.ini -COPY nginx.conf /etc/nginx/nginx.conf -COPY supervised.conf /etc/supervisor/conf.d/supervised.conf - -ADD https://getcomposer.org/composer.phar /usr/local/bin/composer -RUN chmod 755 /usr/local/bin/composer - -WORKDIR /var/www -RUN git clone https://github.com/shaarli/Shaarli.git shaarli \ - && cd shaarli \ - && composer --prefer-dist install -RUN rm -rf html \ - && echo "" > index.php \ - && chown -R www-data:www-data . - -VOLUME /var/www/shaarli/data - -EXPOSE 80 - -CMD ["/usr/bin/supervisord", "-n", "-c", "/etc/supervisor/supervisord.conf"] diff --git a/docker/development/IMAGE.md b/docker/development/IMAGE.md deleted file mode 100644 index e2ff0f0e..00000000 --- a/docker/development/IMAGE.md +++ /dev/null @@ -1,10 +0,0 @@ -## shaarli:dev -- [Debian 8 Jessie](https://hub.docker.com/_/debian/) -- [PHP5-FPM](http://php-fpm.org/) -- [Nginx](http://nginx.org/) -- [Shaarli](https://github.com/shaarli/Shaarli) - -### Development tools -- [composer](https://getcomposer.org/) -- [git](http://git-scm.com/) -- [nano](http://www.nano-editor.org/) diff --git a/docker/development/nginx.conf b/docker/development/nginx.conf deleted file mode 100644 index 79c45bfe..00000000 --- a/docker/development/nginx.conf +++ /dev/null @@ -1,80 +0,0 @@ -user www-data www-data; -daemon off; -worker_processes 4; - -events { - worker_connections 768; -} - -http { - include mime.types; - default_type application/octet-stream; - keepalive_timeout 20; - - client_max_body_size 10m; - - index index.html index.php; - - server { - listen 80; - root /var/www/shaarli; - - access_log /var/log/nginx/shaarli.access.log; - error_log /var/log/nginx/shaarli.error.log; - - location /phpinfo/ { - # add a PHP info page for convenience - fastcgi_pass unix:/var/run/php5-fpm.sock; - fastcgi_index index.php; - fastcgi_param SCRIPT_FILENAME /var/www/index.php; - include fastcgi_params; - } - - location ~ /\. { - # deny access to dotfiles - access_log off; - log_not_found off; - deny all; - } - - location ~ ~$ { - # deny access to temp editor files, e.g. "script.php~" - access_log off; - log_not_found off; - deny all; - } - - location ~* \.(?:ico|css|js|gif|jpe?g|png)$ { - # cache static assets - expires max; - add_header Pragma public; - add_header Cache-Control "public, must-revalidate, proxy-revalidate"; - } - - location = /favicon.ico { - # serve the Shaarli favicon from its custom location - alias /var/www/shaarli/images/favicon.ico; - } - - location / { - # Slim - rewrite URLs - try_files $uri /index.php$is_args$args; - } - - location ~ (index)\.php$ { - # Slim - split URL path into (script_filename, path_info) - try_files $uri =404; - fastcgi_split_path_info ^(.+\.php)(/.+)$; - - # filter and proxy PHP requests to PHP-FPM - fastcgi_pass unix:/var/run/php5-fpm.sock; - fastcgi_index index.php; - include fastcgi.conf; - } - - location ~ \.php$ { - # deny access to all other PHP scripts - deny all; - } - } -} diff --git a/docker/development/supervised.conf b/docker/development/supervised.conf deleted file mode 100644 index 5acd9795..00000000 --- a/docker/development/supervised.conf +++ /dev/null @@ -1,13 +0,0 @@ -[program:php5-fpm] -command=/usr/sbin/php5-fpm -F -priority=5 -autostart=true -autorestart=true - -[program:nginx] -command=/usr/sbin/nginx -priority=10 -autostart=true -autorestart=true -stdout_events_enabled=true -stderr_events_enabled=true diff --git a/mkdocs.yml b/mkdocs.yml index d6dd3fc2..cbac149a 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -16,10 +16,10 @@ pages: - Shaarli configuration: Shaarli-configuration.md - Plugins: Plugins.md - Docker: - - Docker 101: Docker-101.md - - Shaarli images: Shaarli-images.md - - Reverse proxy configuration: Reverse-proxy-configuration.md - - Docker resources: Docker-resources.md + - Docker 101: docker/docker-101.md + - Shaarli images: docker/shaarli-images.md + - Reverse proxy configuration: docker/reverse-proxy-configuration.md + - Docker resources: docker/resources.md - Usage: - Features: Features.md - Bookmarklet: Bookmarklet.md -- cgit v1.2.3