Merge pull request #13 from nupplaphil/readmes

Adding READMEs

.examples/README.md

@@ -0,0 +1,69 @@
+# Examples section
+
+In this subfolder are some examples how to use the docker images.
+There are two section:
+
+* [`dockerfiles`](https://github.com/friendica/docker/tree/master/.examples/dockerfiles)
+* [`docker-compose`](https://github.com/friendica/docker/tree/master/.examples/docker-compose)
+
+The `dockerfiles` are derived images that add or alter certain functionalities of the default docker images.
+In the `docker-compose` subfolder are examples for deployment of the application.
+
+## Dockerfiles
+
+The Dockerfiles use the default images as base image and build on top of it.
+
+Examples | Descriptions
+-------- | -------
+[cron](https://github.com/friendica/docker/tree/master/.examples/dockerfiles/cron) | uses supervisor to run the cron job inside the container (so no extra container is needed).
+[smtp](https://github.com/friendica/docker/tree/master/.examples/dockerfiles/smtp) | adds dependencies required to use SMTP as mail relay/smarthost
+
+## docker-compose
+
+In `docker-compose` additional services are bundled to create a complex Friendica installation.
+The examples are designed to run out-of-the-box.
+
+Before running the examples, you have to modify the `db.env` and `docker-compose.yml` file and fill in your custom information.
+
+The docker-compose examples make heavily use of derived Dockerfiles to add configuration files into the containers.
+This way they should also work on remote docker systems as _Docker for Windows_.
+when running docker-compose on the same host as the docker daemon, another possibility would be to simply mount the files in the volumes section in the `docker-compose.yml` file.
+
+### insecure
+
+This examples should only be used for **testing** on the local network because it uses a unencrypted http connection.
+When you want to have your server reachable from the internet adding HTTPS-encryption is mandatory!
+For this use one of the [with-traefik-proxy](#with-traefik-proxy) examples.
+
+To use this example complete the following steps:
+
+1. choose a password for the database user in `db.env` behind `MYSQL_PASSWORD=`
+2. run `docker-compose build --pull` to pull the mose recent base images and build the custom dockerfiles
+3. start Friendica with `docker-compose up -d`
+
+If you want to update your installation to a newer version, repeat 3 and 4.
+**Note**: If you are on a develop branch (*-dev or *-rc) you have to update Friendica with the command `docker-compose exec app friendica update`
+
+### with-traefik-proxy
+
+The traefik proxy adds a proxy layer between Friendica and the internet.
+The proxy is designed to server multiple sites on the same host machine.
+
+The advantage in adding this layer is the ability to use [Let's Encrypt](https://letsencrypt.org/) out certification handling of the box.
+
+Therefore you have to use adjust the `labels:` inside the `docker-compose.yml` to let traefik know what domains it should route and what certifications it should request.
+
+To use this example complete the following steps:
+
+1. open `docker-compose.yml`
+   1. insert your friendica domain behind `hostname:`
+   2. insert your friendica domain at `traefik.friendica.rule=Host:friendica.local`
+2. choose a password for the database user in `db.env` behind `MYSQL_PASSWORD=`
+3. open `proxy/traefik.toml`
+   1. replace `domain = "example.org"` with your friendica domain
+   2. replace `email = "root@example.org"` with a valid email
+4. run `docker-compose build --pull` to pull the most recent base images and build the custom dockerfiles
+5. start Friendica with `docker-compose up -d`
+
+If you want to update your installation to a newer version, repeat 4 and 5.
+**Note**: If you are on a develop branch (*-dev or *-rc) you have to update Friendica with the command `docker-compose exec app friendica update`

README-MAINTENANCE.md

@@ -0,0 +1,83 @@
+# How to maintain this repository
+
+The structure and usage of this repository is influenced by other, official docker repositories.
+
+# Version directories
+
+**This is important.**
+Never ever change a file/folder inside a directory without a `.` at the beginning (`2018.05-rc`, ...).
+This folder will get updated automatically based on the templates you want to change.
+All changes in such folders will get overwritten during an update.
+
+# [`.bin`](https://github.com/friendica/docker/tree/master/.bin)
+
+This directory holds the binary/shell files for docker images.
+They get copied into the docker images at `/usr/local/bin`.
+
+# [`.config`](https://github.com/friendica/docker/tree/master/.config)
+
+This directory holds the config files for docker images.
+They get copied into the docker images at `/usr/src/config`.
+
+## `htconfig.php`
+
+This file is based on the sample [`htconfig.php`](https://github.com/friendica/friendica/blob/559250b8b3a7a5d0e524d3e3e2d347d18d6c3a2a/htconfig.php) in the Friendica repository.
+
+The differences:
+- Removed the `die()` at the beginning
+- Removed all hard-coded DB settings
+- Added environment variables for mailname, tz, language
+
+# Templates & shell-scripts
+ 
+- If you want to update/upgrade Dockerfiles, use the right `*.template` file for it.
+- If you want to update/change the behavior of **every** start of Docker-image, change `docker-entrypoint.sh`
+- If you want to update/change the behavior how cronjobs will get started, change `docker-cron.sh` 
+
+# Maintenance scripts
+
+There are two important scripts in this repository for maintenance.
+
+## update.sh
+   
+Creates a directory and the necessary files for each combination of version (2018.05-rc, 3.6, ...) and variant (apache, fpm, fpm-alpine):
+
+- Creating the right `Dockerfile` (from one of the two *.template files)
+- Creating the `docker-*.sh` files (copy as *.sh)
+- Coping `/.bin/*` to `bin/*`
+- Coping `/.config/*` to `config/*`
+- Recreating the version/variant environment in `.travis.yml` 
+   
+If you want to update the Docker-images to a newer version, just change the list in `update.sh` at
+```shell
+versions=(
+  2018.05-rc
+)
+```
+   
+# generate-stackbrew-library.sh
+   
+This file automatically creates a "manifest" for the docker-images.
+Like:
+
+```console   
+# This file is generated via https://github.com/friendica/docker/blob/b46fae917321394e1482df59dc4e39daffbe5c59/generate-stackbrew-library.sh
+Maintainers: Friendica <info@friendi.ca> (@friendica), Philipp Holzer <admin@philipp.info> (@[secure])
+GitRepo: https://github.com/friendica/docker.git
+
+Tags: 2018.05-rc-apache, rc-apache, apache, stable-apache, production-apache, 2018.05-rc, rc, latest, stable, production
+Architectures: amd64, arm32v5, arm32v7, arm64v8, i386, ppc64le, s390x
+GitCommit: b46fae917321394e1482df59dc4e39daffbe5c59
+Directory: 2018.05-rc/apache
+
+Tags: 2018.05-rc-fpm, rc-fpm, fpm, stable-fpm, production-fpm
+Architectures: amd64, arm32v5, arm32v7, arm64v8, i386, ppc64le, s390x
+GitCommit: b46fae917321394e1482df59dc4e39daffbe5c59
+Directory: 2018.05-rc/fpm
+
+Tags: 2018.05-rc-fpm-alpine, rc-fpm-alpine, fpm-alpine, stable-fpm-alpine, production-fpm-alpine
+Architectures: amd64, arm32v6, arm64v8, i386, ppc64le, s390x
+GitCommit: b46fae917321394e1482df59dc4e39daffbe5c59
+Directory: 2018.05-rc/fpm-alpine
+This is the input-file for the official-images in a later step :-)
+```

README.md

@@ -23,6 +23,8 @@ The second option is a `fpm` container.
 It is based on the [php-fpm](https://hub.docker.com/_/php/) image and runs a fastCGI-Process that serves your Friendica server.
 To use this image it must be combined with any Webserver that can proxy the http requests to the FastCGI-port of the container.
 
+[![Try in PWD](https://github.com/play-with-docker/stacks/raw/cff22438cb4195ace27f9b15784bbb497047afa7/assets/images/button.png)](http://play-with-docker.com?stack=https://raw.githubusercontent.com/friendica/docker/b9ed3e8ce68eaf89b08269a15f6360abc2fce544/stack.yml)
+
 ## Using the apache image
 
 You need at least one other mariadb/mysql-container to link it to Friendica.