This is page 20 of 22. Use http://codebase.md/id/docs/get_started/create/presentation_layout.html?lines=false&page={x} to view the full context.
# Directory Structure
```
├── .ci
│ ├── check-markdownfmt.sh
│ ├── check-metadata.sh
│ ├── check-pr-no-readme.sh
│ ├── check-required-files.sh
│ ├── check-short.sh
│ ├── check-ymlfmt.sh
│ └── get-markdownfmt.sh
├── .common-templates
│ ├── maintainer-community.md
│ ├── maintainer-docker.md
│ ├── maintainer-hashicorp.md
│ └── maintainer-influxdata.md
├── .dockerignore
├── .github
│ └── workflows
│ └── ci.yml
├── .template-helpers
│ ├── arches.sh
│ ├── autogenerated-warning.md
│ ├── compose.md
│ ├── generate-dockerfile-links-partial.sh
│ ├── generate-dockerfile-links-partial.tmpl
│ ├── get-help.md
│ ├── issues.md
│ ├── license-common.md
│ ├── template.md
│ ├── variant-alpine.md
│ ├── variant-default-buildpack-deps.md
│ ├── variant-default-debian.md
│ ├── variant-default-ubuntu.md
│ ├── variant-onbuild.md
│ ├── variant-slim.md
│ ├── variant-windowsservercore.md
│ ├── variant.md
│ └── variant.sh
├── adminer
│ ├── compose.yaml
│ ├── content.md
│ ├── github-repo
│ ├── license.md
│ ├── logo.png
│ ├── maintainer.md
│ ├── metadata.json
│ ├── README-short.txt
│ └── README.md
├── aerospike
│ ├── content.md
│ ├── github-repo
│ ├── issues.md
│ ├── license.md
│ ├── logo.png
│ ├── maintainer.md
│ ├── metadata.json
│ ├── README-short.txt
│ └── README.md
├── almalinux
│ ├── content.md
│ ├── github-repo
│ ├── issues.md
│ ├── license.md
│ ├── logo.png
│ ├── maintainer.md
│ ├── metadata.json
│ ├── README-short.txt
│ └── README.md
├── alpine
│ ├── content.md
│ ├── github-repo
│ ├── license.md
│ ├── logo.png
│ ├── maintainer.md
│ ├── metadata.json
│ ├── README-short.txt
│ └── README.md
├── alt
│ ├── content.md
│ ├── github-repo
│ ├── issues.md
│ ├── license.md
│ ├── logo.png
│ ├── maintainer.md
│ ├── metadata.json
│ ├── README-short.txt
│ └── README.md
├── amazoncorretto
│ ├── content.md
│ ├── github-repo
│ ├── license.md
│ ├── logo.png
│ ├── maintainer.md
│ ├── metadata.json
│ ├── README-short.txt
│ └── README.md
├── amazonlinux
│ ├── content.md
│ ├── github-repo
│ ├── issues.md
│ ├── license.md
│ ├── logo.png
│ ├── maintainer.md
│ ├── metadata.json
│ ├── README-short.txt
│ └── README.md
├── api-firewall
│ ├── content.md
│ ├── github-repo
│ ├── license.md
│ ├── logo.svg
│ ├── maintainer.md
│ ├── metadata.json
│ ├── README-short.txt
│ └── README.md
├── arangodb
│ ├── content.md
│ ├── github-repo
│ ├── license.md
│ ├── logo.png
│ ├── maintainer.md
│ ├── metadata.json
│ ├── README-short.txt
│ └── README.md
├── archlinux
│ ├── content.md
│ ├── github-repo
│ ├── issues.md
│ ├── license.md
│ ├── logo.png
│ ├── maintainer.md
│ ├── metadata.json
│ ├── README-short.txt
│ └── README.md
├── backdrop
│ ├── compose.yaml
│ ├── content.md
│ ├── github-repo
│ ├── license.md
│ ├── logo.png
│ ├── maintainer.md
│ ├── metadata.json
│ ├── README-short.txt
│ └── README.md
├── bash
│ ├── content.md
│ ├── github-repo
│ ├── license.md
│ ├── logo.png
│ ├── maintainer.md
│ ├── metadata.json
│ ├── README-short.txt
│ └── README.md
├── bonita
│ ├── compose.yaml
│ ├── content.md
│ ├── get-help.md
│ ├── github-repo
│ ├── issues.md
│ ├── license.md
│ ├── logo.png
│ ├── maintainer.md
│ ├── metadata.json
│ ├── README-short.txt
│ └── README.md
├── buildpack-deps
│ ├── content.md
│ ├── github-repo
│ ├── license.md
│ ├── logo.png
│ ├── maintainer.md
│ ├── metadata.json
│ ├── README-short.txt
│ └── README.md
├── busybox
│ ├── content.md
│ ├── github-repo
│ ├── license.md
│ ├── logo.png
│ ├── maintainer.md
│ ├── metadata.json
│ ├── README-short.txt
│ ├── README.md
│ ├── variant-glibc.md
│ ├── variant-musl.md
│ ├── variant-uclibc.md
│ └── variant.md
├── caddy
│ ├── content.md
│ ├── get-help.md
│ ├── github-repo
│ ├── license.md
│ ├── logo-120.png
│ ├── logo.png
│ ├── maintainer.md
│ ├── metadata.json
│ ├── README-short.txt
│ └── README.md
├── cassandra
│ ├── content.md
│ ├── github-repo
│ ├── license.md
│ ├── logo.png
│ ├── maintainer.md
│ ├── metadata.json
│ ├── README-short.txt
│ └── README.md
├── chronograf
│ ├── content.md
│ ├── github-repo
│ ├── license.md
│ ├── logo.png
│ ├── maintainer.md
│ ├── metadata.json
│ ├── README-short.txt
│ └── README.md
├── cirros
│ ├── content.md
│ ├── github-repo
│ ├── license.md
│ ├── logo.png
│ ├── maintainer.md
│ ├── metadata.json
│ ├── README-short.txt
│ └── README.md
├── clearlinux
│ ├── content.md
│ ├── github-repo
│ ├── license.md
│ ├── logo.png
│ ├── maintainer.md
│ ├── metadata.json
│ ├── README-short.txt
│ └── README.md
├── clefos
│ ├── content.md
│ ├── deprecated.md
│ ├── github-repo
│ ├── issues.md
│ ├── license.md
│ ├── logo.png
│ ├── maintainer.md
│ ├── metadata.json
│ ├── README-short.txt
│ └── README.md
├── clickhouse
│ ├── content.md
│ ├── github-repo
│ ├── license.md
│ ├── logo.svg
│ ├── maintainer.md
│ ├── metadata.json
│ ├── README-short.txt
│ └── README.md
├── clojure
│ ├── content.md
│ ├── github-repo
│ ├── license.md
│ ├── logo.png
│ ├── maintainer.md
│ ├── metadata.json
│ ├── README-short.txt
│ └── README.md
├── composer
│ ├── content.md
│ ├── github-repo
│ ├── license.md
│ ├── logo.png
│ ├── maintainer.md
│ ├── metadata.json
│ ├── README-short.txt
│ └── README.md
├── convertigo
│ ├── content.md
│ ├── github-repo
│ ├── license.md
│ ├── logo.png
│ ├── maintainer.md
│ ├── metadata.json
│ ├── README-short.txt
│ └── README.md
├── couchbase
│ ├── content.md
│ ├── github-repo
│ ├── license.md
│ ├── logo.png
│ ├── maintainer.md
│ ├── metadata.json
│ ├── README-short.txt
│ └── README.md
├── couchdb
│ ├── content.md
│ ├── github-repo
│ ├── license.md
│ ├── logo.png
│ ├── maintainer.md
│ ├── metadata.json
│ ├── README-short.txt
│ └── README.md
├── crate
│ ├── content.md
│ ├── get-help.md
│ ├── github-repo
│ ├── license.md
│ ├── logo.svg
│ ├── maintainer.md
│ ├── metadata.json
│ ├── README-short.txt
│ └── README.md
├── dart
│ ├── content.md
│ ├── github-repo
│ ├── license.md
│ ├── logo.svg
│ ├── maintainer.md
│ ├── metadata.json
│ ├── README-short.txt
│ └── README.md
├── debian
│ ├── content.md
│ ├── github-repo
│ ├── license.md
│ ├── logo.png
│ ├── maintainer.md
│ ├── metadata.json
│ ├── README-short.txt
│ ├── README.md
│ ├── variant-slim.md
│ └── variant.md
├── docker
│ ├── content.md
│ ├── github-repo
│ ├── license.md
│ ├── logo.png
│ ├── maintainer.md
│ ├── metadata.json
│ ├── README-short.txt
│ ├── README.md
│ ├── variant-rootless.md
│ └── variant-windowsservercore.md
├── Dockerfile
├── drupal
│ ├── compose.yaml
│ ├── content.md
│ ├── github-repo
│ ├── license.md
│ ├── logo.svg
│ ├── maintainer.md
│ ├── metadata.json
│ ├── README-short.txt
│ ├── README.md
│ └── variant-fpm.md
├── eclipse-mosquitto
│ ├── content.md
│ ├── github-repo
│ ├── license.md
│ ├── logo.png
│ ├── maintainer.md
│ ├── metadata.json
│ ├── README-short.txt
│ └── README.md
├── eclipse-temurin
│ ├── content.md
│ ├── get-help.md
│ ├── github-repo
│ ├── issues.md
│ ├── license.md
│ ├── logo.png
│ ├── maintainer.md
│ ├── metadata.json
│ ├── README-short.txt
│ └── README.md
├── eggdrop
│ ├── content.md
│ ├── github-repo
│ ├── license.md
│ ├── logo.png
│ ├── maintainer.md
│ ├── metadata.json
│ ├── README-short.txt
│ └── README.md
├── elasticsearch
│ ├── compose.yaml
│ ├── content.md
│ ├── get-help.md
│ ├── github-repo
│ ├── issues.md
│ ├── license.md
│ ├── logo.png
│ ├── maintainer.md
│ ├── metadata.json
│ ├── README-short.txt
│ ├── README.md
│ └── variant-alpine.md
├── elixir
│ ├── content.md
│ ├── github-repo
│ ├── license.md
│ ├── logo.png
│ ├── maintainer.md
│ ├── metadata.json
│ ├── README-short.txt
│ └── README.md
├── emqx
│ ├── content.md
│ ├── get-help.md
│ ├── github-repo
│ ├── license.md
│ ├── logo.svg
│ ├── maintainer.md
│ ├── metadata.json
│ ├── README-short.txt
│ └── README.md
├── erlang
│ ├── content.md
│ ├── github-repo
│ ├── license.md
│ ├── logo.png
│ ├── maintainer.md
│ ├── metadata.json
│ ├── README-short.txt
│ └── README.md
├── fedora
│ ├── content.md
│ ├── github-repo
│ ├── issues.md
│ ├── license.md
│ ├── logo.png
│ ├── maintainer.md
│ ├── metadata.json
│ ├── README-short.txt
│ └── README.md
├── flink
│ ├── content.md
│ ├── get-help.md
│ ├── github-repo
│ ├── issues.md
│ ├── license.md
│ ├── logo.png
│ ├── maintainer.md
│ ├── metadata.json
│ ├── README-short.txt
│ └── README.md
├── fluentd
│ ├── content.md
│ ├── github-repo
│ ├── license.md
│ ├── logo.png
│ ├── maintainer.md
│ ├── metadata.json
│ ├── README-short.txt
│ └── README.md
├── friendica
│ ├── compose.yaml
│ ├── content.md
│ ├── github-repo
│ ├── license.md
│ ├── logo.svg
│ ├── maintainer.md
│ ├── metadata.json
│ ├── README-short.txt
│ └── README.md
├── gazebo
│ ├── content.md
│ ├── github-repo
│ ├── license.md
│ ├── logo.png
│ ├── maintainer.md
│ ├── metadata.json
│ ├── README-short.txt
│ └── README.md
├── gcc
│ ├── content.md
│ ├── github-repo
│ ├── license.md
│ ├── logo.png
│ ├── maintainer.md
│ ├── metadata.json
│ ├── README-short.txt
│ └── README.md
├── generate-repo-stub-readme.sh
├── geonetwork
│ ├── compose.yaml
│ ├── content.md
│ ├── github-repo
│ ├── license.md
│ ├── logo.png
│ ├── maintainer.md
│ ├── metadata.json
│ ├── README-short.txt
│ ├── README.md
│ ├── variant-postgres.md
│ └── variant.md
├── get-categories.sh
├── ghost
│ ├── compose.yaml
│ ├── content.md
│ ├── github-repo
│ ├── license.md
│ ├── logo.png
│ ├── maintainer.md
│ ├── metadata.json
│ ├── README-short.txt
│ └── README.md
├── golang
│ ├── content.md
│ ├── github-repo
│ ├── license.md
│ ├── logo.png
│ ├── maintainer.md
│ ├── metadata.json
│ ├── README-short.txt
│ ├── README.md
│ ├── variant-alpine.md
│ └── variant-tip.md
├── gradle
│ ├── content.md
│ ├── github-repo
│ ├── license.md
│ ├── logo.png
│ ├── maintainer.md
│ ├── metadata.json
│ ├── README-short.txt
│ └── README.md
├── groovy
│ ├── content.md
│ ├── github-repo
│ ├── license.md
│ ├── logo.png
│ ├── maintainer.md
│ ├── metadata.json
│ ├── README-short.txt
│ └── README.md
├── haproxy
│ ├── content.md
│ ├── github-repo
│ ├── license.md
│ ├── logo.png
│ ├── maintainer.md
│ ├── metadata.json
│ ├── README-short.txt
│ └── README.md
├── haskell
│ ├── content.md
│ ├── github-repo
│ ├── license.md
│ ├── logo.png
│ ├── maintainer.md
│ ├── metadata.json
│ ├── README-short.txt
│ ├── README.md
│ └── variant-slim.md
├── haxe
│ ├── content.md
│ ├── github-repo
│ ├── license.md
│ ├── logo.png
│ ├── maintainer.md
│ ├── metadata.json
│ ├── README-short.txt
│ └── README.md
├── hello-world
│ ├── content.md
│ ├── github-repo
│ ├── license.md
│ ├── logo.png
│ ├── maintainer.md
│ ├── metadata.json
│ ├── README-short.txt
│ ├── README.md
│ └── update.sh
├── hitch
│ ├── content.md
│ ├── github-repo
│ ├── license.md
│ ├── maintainer.md
│ ├── metadata.json
│ ├── README-short.txt
│ └── README.md
├── httpd
│ ├── content.md
│ ├── github-repo
│ ├── license.md
│ ├── logo.png
│ ├── maintainer.md
│ ├── metadata.json
│ ├── README-short.txt
│ └── README.md
├── hylang
│ ├── content.md
│ ├── github-repo
│ ├── license.md
│ ├── logo.png
│ ├── maintainer.md
│ ├── metadata.json
│ ├── README-short.txt
│ └── README.md
├── ibm-semeru-runtimes
│ ├── content.md
│ ├── github-repo
│ ├── issues.md
│ ├── license.md
│ ├── logo.svg
│ ├── maintainer.md
│ ├── metadata.json
│ ├── README-short.txt
│ └── README.md
├── ibmjava
│ ├── content.md
│ ├── get-help.md
│ ├── github-repo
│ ├── issues.md
│ ├── license.md
│ ├── maintainer.md
│ ├── metadata.json
│ ├── README-short.txt
│ └── README.md
├── influxdb
│ ├── content.md
│ ├── github-repo
│ ├── license.md
│ ├── logo.png
│ ├── maintainer.md
│ ├── metadata.json
│ ├── README-short.txt
│ ├── README.md
│ ├── variant-data.md
│ └── variant-meta.md
├── irssi
│ ├── content.md
│ ├── github-repo
│ ├── license.md
│ ├── logo.png
│ ├── maintainer.md
│ ├── metadata.json
│ ├── README-short.txt
│ └── README.md
├── jetty
│ ├── content.md
│ ├── github-repo
│ ├── license.md
│ ├── logo.png
│ ├── maintainer.md
│ ├── metadata.json
│ ├── README-short.txt
│ └── README.md
├── joomla
│ ├── compose.yaml
│ ├── content.md
│ ├── github-repo
│ ├── license.md
│ ├── logo.png
│ ├── maintainer.md
│ ├── metadata.json
│ ├── README-short.txt
│ └── README.md
├── jruby
│ ├── content.md
│ ├── github-repo
│ ├── license.md
│ ├── logo.png
│ ├── maintainer.md
│ ├── metadata.json
│ ├── README-short.txt
│ └── README.md
├── julia
│ ├── content.md
│ ├── github-repo
│ ├── license.md
│ ├── logo.png
│ ├── maintainer.md
│ ├── metadata.json
│ ├── README-short.txt
│ └── README.md
├── kapacitor
│ ├── content.md
│ ├── github-repo
│ ├── license.md
│ ├── logo.png
│ ├── maintainer.md
│ ├── metadata.json
│ ├── README-short.txt
│ └── README.md
├── kibana
│ ├── compose.yaml
│ ├── content.md
│ ├── get-help.md
│ ├── github-repo
│ ├── issues.md
│ ├── license.md
│ ├── logo.png
│ ├── maintainer.md
│ ├── metadata.json
│ ├── README-short.txt
│ └── README.md
├── kong
│ ├── content.md
│ ├── github-repo
│ ├── license.md
│ ├── logo.png
│ ├── maintainer.md
│ ├── metadata.json
│ ├── README-short.txt
│ └── README.md
├── krakend
│ ├── content.md
│ ├── get-help.md
│ ├── github-repo
│ ├── license.md
│ ├── logo-120.png
│ ├── logo.png
│ ├── maintainer.md
│ ├── metadata.json
│ ├── README-short.txt
│ └── README.md
├── LICENSE
├── lightstreamer
│ ├── content.md
│ ├── github-repo
│ ├── license.md
│ ├── logo.png
│ ├── maintainer.md
│ ├── metadata.json
│ ├── README-short.txt
│ └── README.md
├── liquibase
│ ├── content.md
│ ├── github-repo
│ ├── license.md
│ ├── logo.png
│ ├── maintainer.md
│ ├── metadata.json
│ ├── README-short.txt
│ └── README.md
├── logstash
│ ├── content.md
│ ├── get-help.md
│ ├── github-repo
│ ├── issues.md
│ ├── license.md
│ ├── logo.png
│ ├── maintainer.md
│ ├── metadata.json
│ ├── README-short.txt
│ ├── README.md
│ └── variant-alpine.md
├── mageia
│ ├── content.md
│ ├── github-repo
│ ├── license.md
│ ├── logo.png
│ ├── maintainer.md
│ ├── metadata.json
│ ├── README-short.txt
│ └── README.md
├── mariadb
│ ├── compose.yaml
│ ├── content.md
│ ├── get-help.md
│ ├── github-repo
│ ├── issues.md
│ ├── license.md
│ ├── logo.png
│ ├── maintainer.md
│ ├── metadata.json
│ ├── README-short.txt
│ └── README.md
├── markdownfmt.sh
├── matomo
│ ├── content.md
│ ├── github-repo
│ ├── license.md
│ ├── logo.png
│ ├── maintainer.md
│ ├── metadata.json
│ ├── README-short.txt
│ └── README.md
├── maven
│ ├── content.md
│ ├── github-repo
│ ├── license.md
│ ├── logo.png
│ ├── maintainer.md
│ ├── metadata.json
│ ├── README-short.txt
│ └── README.md
├── mediawiki
│ ├── compose.yaml
│ ├── content.md
│ ├── github-repo
│ ├── issues.md
│ ├── license.md
│ ├── logo.svg
│ ├── maintainer.md
│ ├── metadata.json
│ ├── README-short.txt
│ └── README.md
├── memcached
│ ├── content.md
│ ├── github-repo
│ ├── license.md
│ ├── maintainer.md
│ ├── metadata.json
│ ├── README-short.txt
│ └── README.md
├── metadata.json
├── metadata.sh
├── mongo
│ ├── compose.yaml
│ ├── content.md
│ ├── github-repo
│ ├── license.md
│ ├── maintainer.md
│ ├── metadata.json
│ ├── README-short.txt
│ └── README.md
├── mongo-express
│ ├── content.md
│ ├── github-repo
│ ├── license.md
│ ├── logo.png
│ ├── maintainer.md
│ ├── metadata.json
│ ├── README-short.txt
│ └── README.md
├── monica
│ ├── content.md
│ ├── github-repo
│ ├── license.md
│ ├── logo.svg
│ ├── maintainer.md
│ ├── metadata.json
│ ├── README-short.txt
│ └── README.md
├── mono
│ ├── content.md
│ ├── deprecated.md
│ ├── github-repo
│ ├── license.md
│ ├── logo.png
│ ├── maintainer.md
│ ├── metadata.json
│ ├── README-short.txt
│ └── README.md
├── mysql
│ ├── compose.yaml
│ ├── content.md
│ ├── github-repo
│ ├── license.md
│ ├── logo.png
│ ├── maintainer.md
│ ├── metadata.json
│ ├── README-short.txt
│ └── README.md
├── nats
│ ├── content.md
│ ├── github-repo
│ ├── license.md
│ ├── logo.png
│ ├── maintainer.md
│ ├── metadata.json
│ ├── README-short.txt
│ └── README.md
├── neo4j
│ ├── content.md
│ ├── get-help.md
│ ├── github-repo
│ ├── license.md
│ ├── logo.png
│ ├── maintainer.md
│ ├── metadata.json
│ ├── README-short.txt
│ └── README.md
├── neurodebian
│ ├── content.md
│ ├── github-repo
│ ├── license.md
│ ├── logo.png
│ ├── maintainer.md
│ ├── metadata.json
│ ├── README-short.txt
│ └── README.md
├── nextcloud
│ ├── content.md
│ ├── deprecated.md
│ ├── github-repo
│ ├── license.md
│ ├── maintainer.md
│ ├── metadata.json
│ ├── README-short.txt
│ └── README.md
├── nginx
│ ├── content.md
│ ├── github-repo
│ ├── license.md
│ ├── logo.png
│ ├── maintainer.md
│ ├── metadata.json
│ ├── README-short.txt
│ ├── README.md
│ └── variant-perl.md
├── node
│ ├── content.md
│ ├── github-repo
│ ├── license.md
│ ├── logo.png
│ ├── maintainer.md
│ ├── metadata.json
│ ├── README-short.txt
│ └── README.md
├── notary
│ ├── content.md
│ ├── github-repo
│ ├── license.md
│ ├── maintainer.md
│ ├── metadata.json
│ ├── README-short.txt
│ └── README.md
├── odoo
│ ├── content.md
│ ├── github-repo
│ ├── license.md
│ ├── logo.png
│ ├── maintainer.md
│ ├── metadata.json
│ ├── README-short.txt
│ └── README.md
├── open-liberty
│ ├── content.md
│ ├── get-help.md
│ ├── github-repo
│ ├── license.md
│ ├── logo.png
│ ├── maintainer.md
│ ├── metadata.json
│ ├── README-short.txt
│ └── README.md
├── openjdk
│ ├── content.md
│ ├── deprecated.md
│ ├── github-repo
│ ├── license.md
│ ├── logo.png
│ ├── maintainer.md
│ ├── metadata.json
│ ├── README-short.txt
│ ├── README.md
│ ├── variant-alpine.md
│ ├── variant-oracle.md
│ └── variant-slim.md
├── oraclelinux
│ ├── content.md
│ ├── get-help.md
│ ├── github-repo
│ ├── license.md
│ ├── logo.png
│ ├── maintainer.md
│ ├── metadata.json
│ ├── README-short.txt
│ ├── README.md
│ └── variant-slim.md
├── orientdb
│ ├── content.md
│ ├── github-repo
│ ├── license.md
│ ├── logo.png
│ ├── maintainer.md
│ ├── metadata.json
│ ├── README-short.txt
│ └── README.md
├── parallel-update.sh
├── percona
│ ├── compose.yaml
│ ├── content.md
│ ├── github-repo
│ ├── issues.md
│ ├── license.md
│ ├── logo.png
│ ├── maintainer.md
│ ├── metadata.json
│ ├── README-short.txt
│ └── README.md
├── perl
│ ├── content.md
│ ├── github-repo
│ ├── license.md
│ ├── logo.png
│ ├── maintainer.md
│ ├── metadata.json
│ ├── README-short.txt
│ └── README.md
├── photon
│ ├── content.md
│ ├── github-repo
│ ├── license.md
│ ├── logo.png
│ ├── maintainer.md
│ ├── metadata.json
│ ├── README-short.txt
│ └── README.md
├── php
│ ├── content.md
│ ├── github-repo
│ ├── license.md
│ ├── logo.png
│ ├── maintainer.md
│ ├── metadata.json
│ ├── README-short.txt
│ ├── README.md
│ ├── variant-apache.md
│ ├── variant-cli.md
│ ├── variant-fpm.md
│ └── variant.md
├── php-zendserver
│ ├── content.md
│ ├── deprecated.md
│ ├── github-repo
│ ├── issues.md
│ ├── license.md
│ ├── logo.png
│ ├── maintainer.md
│ ├── metadata.json
│ ├── README-short.txt
│ └── README.md
├── phpmyadmin
│ ├── compose.yaml
│ ├── content.md
│ ├── github-repo
│ ├── license.md
│ ├── logo.png
│ ├── maintainer.md
│ ├── metadata.json
│ ├── README-short.txt
│ └── README.md
├── plone
│ ├── content.md
│ ├── github-repo
│ ├── license.md
│ ├── logo.svg
│ ├── maintainer.md
│ ├── metadata.json
│ ├── README-short.txt
│ └── README.md
├── postfixadmin
│ ├── compose.yaml
│ ├── content.md
│ ├── github-repo
│ ├── license.md
│ ├── logo.png
│ ├── maintainer.md
│ ├── metadata.json
│ ├── README-short.txt
│ ├── README.md
│ ├── variant-apache.md
│ ├── variant-fpm-alpine.md
│ └── variant-fpm.md
├── postgres
│ ├── compose.yaml
│ ├── content.md
│ ├── github-repo
│ ├── license.md
│ ├── logo.png
│ ├── maintainer.md
│ ├── metadata.json
│ ├── README-short.txt
│ └── README.md
├── push.pl
├── push.sh
├── pypy
│ ├── content.md
│ ├── github-repo
│ ├── license.md
│ ├── logo.png
│ ├── maintainer.md
│ ├── metadata.json
│ ├── README-short.txt
│ └── README.md
├── python
│ ├── content.md
│ ├── github-repo
│ ├── license.md
│ ├── logo.png
│ ├── maintainer.md
│ ├── metadata.json
│ ├── README-short.txt
│ ├── README.md
│ └── variant-slim.md
├── r-base
│ ├── content.md
│ ├── github-repo
│ ├── issues.md
│ ├── license.md
│ ├── logo.png
│ ├── maintainer.md
│ ├── metadata.json
│ ├── README-short.txt
│ └── README.md
├── rabbitmq
│ ├── content.md
│ ├── github-repo
│ ├── license.md
│ ├── logo.png
│ ├── maintainer.md
│ ├── metadata.json
│ ├── README-short.txt
│ └── README.md
├── rakudo-star
│ ├── content.md
│ ├── github-repo
│ ├── license.md
│ ├── logo.png
│ ├── maintainer.md
│ ├── metadata.json
│ ├── README-short.txt
│ └── README.md
├── README.md
├── redis
│ ├── content.md
│ ├── github-repo
│ ├── license.md
│ ├── logo.png
│ ├── maintainer.md
│ ├── metadata.json
│ ├── README-short.txt
│ └── README.md
├── redmine
│ ├── compose.yaml
│ ├── content.md
│ ├── github-repo
│ ├── license.md
│ ├── logo.png
│ ├── maintainer.md
│ ├── metadata.json
│ ├── README-short.txt
│ └── README.md
├── registry
│ ├── content.md
│ ├── get-help.md
│ ├── github-repo
│ ├── license.md
│ ├── logo.png
│ ├── maintainer.md
│ ├── metadata.json
│ ├── README-short.txt
│ └── README.md
├── rethinkdb
│ ├── content.md
│ ├── github-repo
│ ├── license.md
│ ├── logo.png
│ ├── maintainer.md
│ ├── metadata.json
│ ├── README-short.txt
│ └── README.md
├── rocket.chat
│ ├── content.md
│ ├── github-repo
│ ├── license.md
│ ├── logo.svg
│ ├── maintainer.md
│ ├── metadata.json
│ ├── README-short.txt
│ └── README.md
├── rockylinux
│ ├── content.md
│ ├── github-repo
│ ├── issues.md
│ ├── license.md
│ ├── logo.png
│ ├── maintainer.md
│ ├── metadata.json
│ ├── README-short.txt
│ └── README.md
├── ros
│ ├── content.md
│ ├── github-repo
│ ├── license.md
│ ├── logo.png
│ ├── maintainer.md
│ ├── metadata.json
│ ├── README-short.txt
│ └── README.md
├── ruby
│ ├── content.md
│ ├── github-repo
│ ├── license.md
│ ├── logo.png
│ ├── maintainer.md
│ ├── metadata.json
│ ├── README-short.txt
│ └── README.md
├── rust
│ ├── content.md
│ ├── github-repo
│ ├── license.md
│ ├── logo.png
│ ├── maintainer.md
│ ├── metadata.json
│ ├── README-short.txt
│ └── README.md
├── sapmachine
│ ├── content.md
│ ├── get-help.md
│ ├── github-repo
│ ├── issues.md
│ ├── license.md
│ ├── logo.png
│ ├── maintainer.md
│ ├── metadata.json
│ ├── README-short.txt
│ └── README.md
├── satosa
│ ├── content.md
│ ├── get-help.md
│ ├── github-repo
│ ├── license.md
│ ├── logo.svg
│ ├── maintainer.md
│ ├── metadata.json
│ ├── README-short.txt
│ └── README.md
├── scratch
│ ├── metadata.json
│ ├── README-short.txt
│ └── README.md
├── silverpeas
│ ├── content.md
│ ├── get-help.md
│ ├── github-repo
│ ├── license.md
│ ├── logo.png
│ ├── maintainer.md
│ ├── metadata.json
│ ├── README-short.txt
│ └── README.md
├── solr
│ ├── content.md
│ ├── get-help.md
│ ├── github-repo
│ ├── issues.md
│ ├── license.md
│ ├── logo.png
│ ├── maintainer.md
│ ├── metadata.json
│ ├── README-short.txt
│ └── README.md
├── sonarqube
│ ├── content.md
│ ├── get-help.md
│ ├── github-repo
│ ├── license.md
│ ├── logo.png
│ ├── maintainer.md
│ ├── metadata.json
│ ├── README-short.txt
│ └── README.md
├── spark
│ ├── content.md
│ ├── get-help.md
│ ├── github-repo
│ ├── issues.md
│ ├── license.md
│ ├── logo.png
│ ├── maintainer.md
│ ├── metadata.json
│ ├── README-short.txt
│ └── README.md
├── spiped
│ ├── content.md
│ ├── github-repo
│ ├── license.md
│ ├── maintainer.md
│ ├── metadata.json
│ ├── README-short.txt
│ └── README.md
├── storm
│ ├── compose.yaml
│ ├── content.md
│ ├── get-help.md
│ ├── github-repo
│ ├── issues.md
│ ├── license.md
│ ├── logo.png
│ ├── maintainer.md
│ ├── metadata.json
│ ├── README-short.txt
│ └── README.md
├── swift
│ ├── content.md
│ ├── get-help.md
│ ├── github-repo
│ ├── issues.md
│ ├── license.md
│ ├── logo.png
│ ├── maintainer.md
│ ├── metadata.json
│ ├── README-short.txt
│ └── README.md
├── swipl
│ ├── content.md
│ ├── get-help.md
│ ├── github-repo
│ ├── license.md
│ ├── logo.png
│ ├── maintainer.md
│ ├── metadata.json
│ ├── README-short.txt
│ └── README.md
├── teamspeak
│ ├── compose.yaml
│ ├── content.md
│ ├── github-repo
│ ├── license.md
│ ├── logo.png
│ ├── maintainer.md
│ ├── metadata.json
│ ├── README-short.txt
│ └── README.md
├── telegraf
│ ├── content.md
│ ├── github-repo
│ ├── license.md
│ ├── logo.png
│ ├── maintainer.md
│ ├── metadata.json
│ ├── README-short.txt
│ └── README.md
├── tomcat
│ ├── content.md
│ ├── github-repo
│ ├── license.md
│ ├── logo.png
│ ├── maintainer.md
│ ├── metadata.json
│ ├── README-short.txt
│ └── README.md
├── tomee
│ ├── content.md
│ ├── github-repo
│ ├── license.md
│ ├── logo.png
│ ├── maintainer.md
│ ├── metadata.json
│ ├── README-short.txt
│ └── README.md
├── traefik
│ ├── content.md
│ ├── github-repo
│ ├── license.md
│ ├── logo.png
│ ├── maintainer.md
│ ├── metadata.json
│ ├── README-short.txt
│ ├── README.md
│ └── variant-alpine.md
├── ubuntu
│ ├── content.md
│ ├── github-repo
│ ├── issues.md
│ ├── license.md
│ ├── logo.png
│ ├── maintainer.md
│ ├── metadata.json
│ ├── README-short.txt
│ └── README.md
├── unit
│ ├── content.md
│ ├── get-help.md
│ ├── github-repo
│ ├── license.md
│ ├── logo.svg
│ ├── maintainer.md
│ ├── metadata.json
│ ├── README-short.txt
│ └── README.md
├── update.sh
├── varnish
│ ├── content.md
│ ├── github-repo
│ ├── license.md
│ ├── logo.png
│ ├── maintainer.md
│ ├── metadata.json
│ ├── README-short.txt
│ └── README.md
├── websphere-liberty
│ ├── content.md
│ ├── get-help.md
│ ├── github-repo
│ ├── license.md
│ ├── logo.png
│ ├── maintainer.md
│ ├── metadata.json
│ ├── README-short.txt
│ └── README.md
├── wordpress
│ ├── compose.yaml
│ ├── content.md
│ ├── github-repo
│ ├── license.md
│ ├── logo.png
│ ├── maintainer.md
│ ├── metadata.json
│ ├── README-short.txt
│ ├── README.md
│ ├── variant-cli.md
│ └── variant-fpm.md
├── xwiki
│ ├── content.md
│ ├── get-help.md
│ ├── github-repo
│ ├── issues.md
│ ├── license.md
│ ├── logo.png
│ ├── maintainer.md
│ ├── metadata.json
│ ├── README-short.txt
│ └── README.md
├── ymlfmt.sh
├── yourls
│ ├── compose.yaml
│ ├── content.md
│ ├── github-repo
│ ├── license.md
│ ├── logo.svg
│ ├── maintainer.md
│ ├── metadata.json
│ ├── README-short.txt
│ ├── README.md
│ └── variant-fpm.md
├── znc
│ ├── content.md
│ ├── github-repo
│ ├── license.md
│ ├── logo.png
│ ├── maintainer.md
│ ├── metadata.json
│ ├── README-short.txt
│ ├── README.md
│ └── variant-slim.md
└── zookeeper
├── compose.yaml
├── content.md
├── github-repo
├── license.md
├── logo.png
├── maintainer.md
├── metadata.json
├── README-short.txt
└── README.md
```
# Files
--------------------------------------------------------------------------------
/bonita/content.md:
--------------------------------------------------------------------------------
```markdown
# What is Bonita?
Bonita is an open-source business process management and workflow suite created in 2001. It was started in France National Institute for Research in Computer Science, and then had incubated several years inside the French computer science company Groupe Bull. Since 2009, the development of Bonita is supported by a company dedicated to this activity: Bonitasoft.
> [wikipedia.org/wiki/Bonita_BPM](http://en.wikipedia.org/wiki/Bonita_BPM)
%%LOGO%%
# How to use this image
## Quick start
```console
$ docker run --name bonita -d -p 8080:8080 %%IMAGE%%
```
This will start a container running [Bonita runtime](https://documentation.bonitasoft.com/bonita/latest/tomcat-bundle): a Tomcat bundle with Bonita Engine + Bonita Portal. With no environment variables specified, it's as if you have launched the bundle on your host using startup.{sh|bat} (with security hardening on REST and HTTP APIs, cf Security part). Bonita uses a H2 database here.
You can access the Bonita Portal on http://localhost:8080/bonita and login using the default credentials: install / install
## Link Bonita to a database
The H2 database allows the Bonita container to work out of the box, but it is not recommended outside a development environment.
As PostgreSQL is the recommended database for qualification and production environments, follow one of these next sections to configure your Bonita container to run on PostgreSQL database. You can work with either a PostgreSQL Container, or PostgreSQL as an installed service.
### PostgreSQL Container
From Bonita 2022.1 onwards, the Bonita docker image does not include configuration scripts to automatically create databases and users anymore.
Therefore the PostgreSQL container needs to be configured to work with Bonita before starting the Bonita container. The configuration of a PostgreSQL database to work with Bonita is described in details in the [database configuration page](https://documentation.bonitasoft.com/bonita/latest/runtime/database-configuration#postgres_setup). + Alternatively, Bonita provides a preconfigured [PostgreSQL image](https://hub.docker.com/r/bonitasoft/bonita-postgres) on docker-hub. + You can run the image with the following command:
```bash
docker run --name mydbpostgres -h <hostname> -d bonitasoft/bonita-postgres:16.4
```
This image is built from the following [GitHub repository](https://github.com/Bonitasoft-Community/bonita-database-docker/tree/main/postgres/16), which can be further adapted/customized to suit your needs.
## %%COMPOSE%%
Run `docker compose up`, wait for it to initialize completely, and visit `http://localhost:8080` or `http://host-ip:8080` (as appropriate).
- Replace `<hostname>` with the one used in the licence generation command
- leave double `$$` untouched
### PostgreSQL as an installed service
If you don't want to run your database in a docker container, the following `env.txt` file needs to be configured and provided to the docker run command:
```properties
DB_VENDOR=postgres
DB_HOST=172.17.0.2
DB_PORT=5432
DB_NAME=custombonitadb
DB_USER=custombonitauser
DB_PASS=custombonitapass
BIZ_DB_NAME=custombusinessdb
BIZ_DB_USER=custombusinessuser
BIZ_DB_PASS=custombusinesspass
```
```bash
docker run --name=bonita -h <hostname> --env-file=env.txt -d -p 8080:8080 %%IMAGE%%
```
## Start Bonita with custom security credentials
```bash
docker run --name=bonita -h <hostname> -e "BONITA_RUNTIME_ADMIN_USERNAME=tech_user" -e "BONITA_RUNTIME_ADMIN_PASSWORD=secret" -e "PLATFORM_LOGIN=pfadmin" -e "PLATFORM_PASSWORD=pfsecret" -d -p 8080:8080 %%IMAGE%%
```
Now you can access the Bonita Runtime on localhost:8080/bonita and login using: tech_user / secret
## Where data are stored
Bonita uses tomcat that writes file to a working directory and a temp directory.
It can be a good practice to mount the following folders into volumes
- `/opt/bonita/server/temp`
- `/opt/bonita/server/work`
## Environment variables
When you start the bonita image, you can adjust the configuration of the Bonita instance by passing one or more environment variables on the docker run command line.
### PLATFORM_LOGIN
This optional environment variable is used in conjunction with PLATFORM_PASSWORD to define the username for the platform administrator. If it is not specified, the default username `platformAdmin` will be used.
### PLATFORM_PASSWORD
This environment variable is recommended for you to use the Bonita image. It sets the platform administrator password for Bonita. If it is not specified, the default password `platform` will be used.
### BONITA_RUNTIME_ADMIN_USERNAME
This optional environment variable is used in conjunction with BONITA_RUNTIME_ADMIN_PASSWORD to define the username for the tenant administrator. If it is not specified, the default username `install` will be used.
### BONITA_RUNTIME_ADMIN_PASSWORD
This environment variable is recommended for you to use the Bonita image. It sets the tenant administrator password for Bonita. If it is not specified, the default password `install` will be used.
### MONITORING_USERNAME
This optional environment variable is used in conjunction with `MONITORING_PASSWORD` to define the access to endpoints protected with [BASIC Auth access](https://en.wikipedia.org/wiki/Basic_access_authentication): it is used for the JMX remote access. If it is not specified, the default monitoring username `monitoring` will be used.
### MONITORING_PASSWORD
This optional environment variable is used in conjunction with `MONITORING_USERNAME` to define the access to endpoints protected with [BASIC Auth access](https://en.wikipedia.org/wiki/Basic_access_authentication): it is used for the JMX remote access. If it is not specified, the default monitoring password `mon1tor1ng_adm1n` will be used.
### HTTP_API
This optional environment variable is used to enable/disable the Bonita HTTP API. The default value is false, which will deactivate the HTTP API. From Bonita 2022.1, HTTP API is protected with [Basic access authentication](https://en.wikipedia.org/wiki/Basic_access_authentication). See the following 2 parameters to configure Basic access authentication.
### HTTP_API_USERNAME
This optional environment variable is used to configure the HTTP API Basic access authentication username. The default value is `http-api`.
### HTTP_API_PASSWORD
This optional environment variable is used to configure the HTTP API Basic access authentication password. There is no default value, and providing a value is mandatory if `HTTP_API=true`.
### JMX_REMOTE_ACCESS
This optional environment variable is used to enable/disable the access to the [JMX console](https://docs.oracle.com/en/java/javase/11/management/using-jconsole.html) from a remote machine. + Default value is `false`. + The host to connect to is the name / IP address of the bonita server, the port to connect to is 9000. + The credentials to connect are the environment variables [MONITORING_USERNAME](#MONITORING_USERNAME), [MONITORING_PASSWORD](#MONITORING_PASSWORD).
### REMOTE_IP_VALVE_ENABLED
This optional environment variable allows to activate/deactivate [reverse proxy redirection](https://documentation.bonitasoft.com/bonita/latest/runtime/reverse-proxy-configuration). Default value is `false`.
### ACCESSLOGS_STDOUT_ENABLED
This optional environment variable allows to activate/deactivate writing Tomcat access logs to standard output. Default value is `false`.
### ACCESSLOGS_FILES_ENABLED
This optional environment variable allows to activate/deactivate writing Tomcat access logs to a specific file. When activated, will write those logs to `/opt/bonita/logs/` *inside* the docker container. In practice, it is only useful when mounting a volume to the aforementioned directory. Default value is `false`.
### ACCESSLOGS_PATH
If `ACCESSLOGS_FILES_ENABLED=true`, this optional environment variable overrides the default path to the access log files. Default value is `/opt/bonita/logs`.
### ACCESSLOGS_PATH_APPEND_HOSTNAME
If `ACCESSLOGS_FILES_ENABLED=true`, this optional environment variable allows to append a subdirectory with the *hostname* to the full path of the directory to put access log files into. Default value is `false`.
### ACCESSLOGS_MAX_DAYS
If `ACCESSLOGS_FILES_ENABLED=true`, this optional environment variable allows to automatically delete access log files after a certain number of days. Default value is `30`.
### HTTP_MAX_THREADS
This optional environment variable allows to specify the maximum Http thread number Tomcat will use to serve HTTP/1.1 requests. Directly modifies the *maxThreads* parameter in the *server.xml* file of the Tomcat inside the docker container. More information on the usefulness of this parameter can be found [here](https://tomcat.apache.org/tomcat-9.0-doc/config/http.html). Default value is `20`.
### JAVA_OPTS
This optional environment variable is used to customize JAVA_OPTS. The default value is -Xms1024m -Xmx1024m -XX:MaxPermSize=256m. The syntax to use is `-e JAVA_OPTS="-Xms2048m -Xmx2048m -XX:MaxPermSize=1024m"`
### DB_VENDOR
This environment variable is automatically set to postgres or mysql if the Bonita container is linked to a PostgreSQL or MySQL database using --link. The default value is h2. It can be overridden if you don't use the --link capability.
### DB_HOST, DB_PORT
These variables are optional, used in conjunction to configure the bonita image to reach the database instance. There are automatically set if --link is used to run the container.
### DB_NAME, DB_USER, DB_PASS
These variables are used in conjunction to define how Bonita should access its database for internal functioning.
`DB_NAME` default value is bonitadb.
`DB_USER` default value is bonitauser.
`DB_PASS` default value is bonitapass.
### BIZ_DB_NAME, BIZ_DB_USER, BIZ_DB_PASS
These variables are used in conjunction to define how Bonita should access the [Business Data](https://documentation.bonitasoft.com/bonita/latest/data/define-and-deploy-the-bdm) database.
`BIZ_DB_NAME` default value is businessdb.
`BIZ_DB_USER` default value is businessuser.
`BIZ_DB_PASS` default value is businesspass.
## Logger configuration
**Since 2022.1**
The logger can be configured by mounting a volume on folder `/opt/bonita/conf/logs` containing the configuration files.
the volume must contain the 2 files [log4j2-loggers.xml](https://raw.githubusercontent.com/bonitasoft/bonita-distrib/10.2.0/tomcat-resources/tomcat-distrib-for-bonita/src/main/resources/tomcat/server/conf/log4j2-loggers.xml) and [log4j2-appenders.xml](https://raw.githubusercontent.com/bonitasoft/bonita-distrib/10.2.0/docker/files/log4j2/log4j2-appenders.xml)
Any change made to one of this 2 files is automatically hot-reloaded and taken into account immediately.
## Security
This Docker image activates both static and dynamic authorization checks by default on REST API. To be consistent, it also deactivates the HTTP API.
- REST API authorization
- [Static authorization checking](https://documentation.bonitasoft.com/bonita/latest/rest-api-authorization#static_authorization)
- [HTTP API](https://documentation.bonitasoft.com/bonita/latest/rest-api-authorization#_activating_and_deactivating_authorization)
For specific needs you can override this behavior by setting HTTP_API to true:
```console
$ docker run -e HTTP_API=true -e HTTP_API_PASSWORD="My-Cust0m_S3cR3T" --name bonita -d -p 8080:8080 %%IMAGE%%
```
## Update from an earlier version of Bonita
For updating from a version before 7.10.0, please refer to the [documentation](https://documentation.bonitasoft.com/bonita/latest/version-update/update-with-migration-tool)
- Stop the container to perform a database backup
```console
$ docker stop bonita
```
- Retrieve the DB container IP
```console
$ docker inspect --format '{{ .NetworkSettings.IPAddress }}' mydbpostgres
172.17.0.26
```
- Dump the database
```console
$ export PGPASSWORD=mysecretpassword
$ pg_dump -O -x -h 172.17.0.26 -U postgres bonitadb > /tmp/bonitadb.sql
```
Note that businessdb won't be updated by the update tool but you may want to also backup/move it.
- Load the dump
```console
$ export PGPASSWORD=mysecretpassword
$ psql -U postgres -h 172.17.0.26 -d postgres -c "CREATE USER newbonitauser WITH PASSWORD 'newbonitapass';"
$ psql -U postgres -h 172.17.0.26 -d postgres -c "CREATE DATABASE newbonitadb OWNER newbonitauser;"
$ export PGPASSWORD=newbonitapass
$ cat /tmp/bonitadb.sql | psql -U newbonitauser -h 172.17.0.26 newbonitadb
```
- Retrieve the last update tool archive from https://www.bonitasoft.com/downloads
```console
unzip bonita-update-tool-3.6.0.zip
```
- Configure the update tool
```console
$ cd bonita-update-tool-3.6.0
```
edit the update tool configuration file `Config.properties` to point towards the database.
```console
$ vim Config.properties
```
For example :
```properties
db.vendor=postgres
db.url=jdbc:postgresql://172.17.0.26:5432/newbonitadb
db.driverClass=org.postgresql.Driver
db.user=newbonitauser
db.password=newbonitapass
```
- Launch the update tool
```console
$ cd bin
$ ./bonita-update-tool
```
- Launch the new container pointing towards the copy of the database.
```console
$ docker run --name=bonita --link mydbpostgres:postgres -e "DB_NAME=newbonitadb" -e "DB_USER=newbonitauser" -e "DB_PASS=newbonitapass" -d -p 8081:8080 %%IMAGE%%:2024.3-u0
```
For more details regarding Bonita update and for version before 7.10.0, see the [documentation](https://documentation.bonitasoft.com/bonita/latest/version-update/migrate-from-an-earlier-version-of-bonita).
```
--------------------------------------------------------------------------------
/phpmyadmin/content.md:
--------------------------------------------------------------------------------
```markdown
# What is phpMyAdmin?
phpMyAdmin is a free software tool written in PHP, intended to handle the administration of MySQL over the Web. phpMyAdmin supports a wide range of operations on MySQL and MariaDB. Frequently used operations (managing databases, tables, columns, relations, indexes, users, permissions, etc) can be performed via the user interface, while you still have the ability to directly execute any SQL statement.
Run phpMyAdmin with Alpine, Apache and PHP FPM.
%%LOGO%%
# How to use this image
All of the following examples will bring you phpMyAdmin on `http://localhost:8080` where you can enjoy your happy MySQL and MariaDB administration.
## Credentials
phpMyAdmin connects using your MySQL server credentials. Please check your corresponding database server image for information on the default username and password or how to specify your own custom credentials during installation.
The official MySQL and MariaDB images use the following environment variables to define these:
- `MYSQL_ROOT_PASSWORD` - This variable is mandatory and specifies the password that will be set for the `root` superuser account.
- `MYSQL_USER`, `MYSQL_PASSWORD` - These variables are optional, used in conjunction to create a new user and to set that user's password.
## Supported Docker Hub tags
The following tags are available:
- `latest`, `fpm`, and `fpm-alpine` are always the most recent released version
- Major versions, such as `5`, `5-fpm`, and `5-fpm-alpine`
- Specific minor versions, such as `5.0`, `5.0-fpm`, and `5-fpm-alpine`
- Specific patch versions, such as `5.0.0`, `5.0.0-fpm`, and `5.0.0-fpm-alpine`. Note that, on rare occasion, there may be an intermediary "docker-only" release, such as 4.9.2-1
A complete list of tags is [available at Docker Hub](https://hub.docker.com/_/phpmyadmin?tab=tags)
## Image variants
We provide three variations:
- "apache" includes a full Apache webserver with PHP and includes everything needed to work out of the box. This is the default when only a version number is requested.
- "fpm" only starts a PHP FPM container. Use this variant if you already have a separate webserver. This includes more tools and is therefore a larger image than the "fpm-alpine" variation.
- "fpm-alpine" has a very small footprint. It is based on Alpine Linux and only starts a PHP FPM process. Use this variant if you already have a separate webserver. If you need more tools that are not available on Alpine Linux, use the fpm image instead.
## Usage with linked server
First you need to run a MySQL or MariaDB server in Docker, and the phpMyAdmin image needs to be linked to the running database container:
```sh
docker run --name phpmyadmin -d --link mysql_db_server:db -p 8080:80 %%IMAGE%%
```
## Usage with external server
You can specify a MySQL host in the `PMA_HOST` environment variable. You can also use `PMA_PORT` to specify the port of the server in case it's not the default one:
```sh
docker run --name phpmyadmin -d -e PMA_HOST=dbhost -p 8080:80 %%IMAGE%%
```
## Usage with arbitrary server
You can use arbitrary servers by adding the environment variable `PMA_ARBITRARY=1` to the startup command:
```sh
docker run --name phpmyadmin -d -e PMA_ARBITRARY=1 -p 8080:80 %%IMAGE%%
```
## Usage with `docker compose` and an arbitrary server
This will run phpMyAdmin with the arbitrary server option - allowing you to specify any MySQL/MariaDB server on the login page.
%%COMPOSE%%
## Adding Custom Configuration
You can add your own custom config.inc.php settings (such as Configuration Storage setup) by creating a file named `config.user.inc.php` with the various user defined settings in it, and then linking it into the container using:
```sh
-v /some/local/directory/config.user.inc.php:/etc/phpmyadmin/config.user.inc.php
```
On the `docker run` line like this:
```sh
docker run --name phpmyadmin -d --link mysql_db_server:db -p 8080:80 -v /some/local/directory/config.user.inc.php:/etc/phpmyadmin/config.user.inc.php %%IMAGE%%
```
Be sure to have `<?php` as your first line of the configuration file or the contents will not be detected as PHP code.
Example:
```php
<?php
$cfg['ShowPhpInfo'] = true; // Adds a link to phpinfo() on the home page
```
See the following links for config file information:
- https://docs.phpmyadmin.net/en/latest/config.html#config
- https://docs.phpmyadmin.net/en/latest/setup.html
## Adding custom configuration in `/etc/phpmyadmin/conf.d`
you can also consider storing your custom configuration files in the folder `/etc/phpmyadmin/conf.d`, which is very suitable for managing multiple phpMyAdmin configuration files for different hosts,Then you can create `server-1.php`, `server-2.php`, or any file name you want, and store them in the conf.d directory mounted on the host.
On the `docker run` line like this:
```sh
docker run --name phpmyadmin -d --link mysql_db_server:db -p 8080:80 -v /some/local/directory/conf.d:/etc/phpmyadmin/conf.d:ro %%IMAGE%%
```
## Usage behind a reverse proxy
Set the variable `PMA_ABSOLUTE_URI` to the fully-qualified path (`https://pma.example.net/`) where the reverse proxy makes phpMyAdmin available.
## Sessions persistence
In order to keep your sessions active between container updates you will need to mount the `/sessions` folder.
```sh
-v /some/local/directory/sessions:/sessions:rw
```
## Connect to the database over SSL
Set the variable `PMA_SSL` to `1` to enable SSL usage from phpMyAdmin to the MySQL server. The default value is `0`. The variable `PMA_SSLS` can be used as a comma seperated sequence of `0` and `1` where multiple hosts are mentioned. Values order must follow the `PMA_HOSTS` and will be computed accordingly.
```sh
docker run --name phpmyadmin -d -e PMA_HOSTS=sslhost -e PMA_SSL=1 -p 8080:80 %%IMAGE%%
```
```sh
docker run --name phpmyadmin -d -e PMA_HOSTS='sslhost,nosslhost' -e PMA_SSLS='1,0' -p 8080:80 %%IMAGE%%
```
## Environment variables summary
- `PMA_ARBITRARY` - when set to 1 connection to the arbitrary server will be allowed
- `PMA_HOST` - define address/host name of the MySQL server
- `PMA_VERBOSE` - define verbose name of the MySQL server
- `PMA_PORT` - define port of the MySQL server
- `PMA_HOSTS` - define comma separated list of address/host names of the MySQL servers
- `PMA_VERBOSES` - define comma separated list of verbose names of the MySQL servers
- `PMA_PORTS` - define comma separated list of ports of the MySQL servers
- `PMA_SOCKET` - define socket file for the MySQL connection
- `PMA_SOCKETS` - define comma separated list of socket files for the MySQL connections
- `PMA_SSL_DIR` - define the path used for SSL files generated from environement variables, default value is `/etc/phpmyadmin/ssl`
- `PMA_SSL` - when set to 1, defines SSL usage for the MySQL connection
- `PMA_SSLS` - comma separated list of `0` and `1` defining SSL usage for the corresponding MySQL connections
- `PMA_SSL_VERIFY` - when set to 1, enables SSL certificate verification for the MySQL connection.
- `PMA_SSL_VERIFIES` - comma-separated list of `0` and `1` to enable or disable SSL certificate verification for multiple MySQL connections.
- `PMA_SSL_CA` - in the context of mutual TLS security, allows setting your CA certificate file as a string inside the default `config.inc.php`.
- `PMA_SSL_CAS` - in the context of mutual TLS security, allows setting multiple CA certificate files as a comma-separated list of strings inside the default `config.inc.php`.
- `PMA_SSL_CERT` - in the context of mutual TLS security, allows setting your certificate file as a string inside the default `config.inc.php`.
- `PMA_SSL_CERTS` - in the context of mutual TLS security, allows setting multiple certificate files as a comma-separated list of strings inside the default `config.inc.php`.
- `PMA_SSL_KEY` - in the context of mutual TLS security, allows setting your private key file as a string inside the default `config.inc.php`.
- `PMA_SSL_KEYS` - in the context of mutual TLS security, allows setting multiple private key files as a comma-separated list of strings inside the default `config.inc.php`.
- `PMA_USER` and `PMA_PASSWORD` - define username and password to use only with the `config` authentication method
- `PMA_ABSOLUTE_URI` - the full URL to phpMyAdmin. Sometimes needed when used in a reverse-proxy configuration. Don't set this unless needed. See [documentation](https://docs.phpmyadmin.net/en/latest/config.html#cfg_PmaAbsoluteUri).
- `PMA_CONFIG_BASE64` - if set, this option will override the default `config.inc.php` with the base64 decoded contents of the variable
- `PMA_USER_CONFIG_BASE64` - if set, this option will override the default `config.user.inc.php` with the base64 decoded contents of the variable
- `PMA_UPLOADDIR` - if defined, this option will set the path where files can be saved to be available to import ([$cfg['UploadDir']](https://docs.phpmyadmin.net/en/latest/config.html#cfg_UploadDir))
- `PMA_SAVEDIR` - if defined, this option will set the path where exported files can be saved ([$cfg['SaveDir']](https://docs.phpmyadmin.net/en/latest/config.html#cfg_SaveDir))
- `PMA_CONTROLHOST` - when set, this points to an alternate database host used for storing the [phpMyAdmin Configuration Storage database](https://docs.phpmyadmin.net/en/latest/setup.html#phpmyadmin-configuration-storage) database
- `PMA_CONTROLPORT` - if set, will override the default port (3306) for connecting to the control host for storing the [phpMyAdmin Configuration Storage database](https://docs.phpmyadmin.net/en/latest/setup.html#phpmyadmin-configuration-storage) database
- `PMA_PMADB` - define the name of the database to be used for the [phpMyAdmin Configuration Storage database](https://docs.phpmyadmin.net/en/latest/setup.html#phpmyadmin-configuration-storage). When not set, the advanced features are not enabled by default: they can still potentially be enabled by the user when logging in with the zero conf (zero configuration) feature. Suggested values: `phpmyadmin` or `pmadb`
- `PMA_CONTROLUSER` - define the username for phpMyAdmin to use for advanced features (the [controluser](https://docs.phpmyadmin.net/en/latest/config.html#cfg_Servers_controluser))
- `PMA_CONTROLPASS` - define the password for phpMyAdmin to use with the [controluser](https://docs.phpmyadmin.net/en/latest/config.html#cfg_Servers_controlpass)
- `PMA_QUERYHISTORYDB` - when set [to true](https://docs.phpmyadmin.net/en/latest/config.html#cfg_QueryHistoryDB), enables storing [SQL history](https://docs.phpmyadmin.net/en/latest/config.html#cfg_Servers_history) to the [phpMyAdmin Configuration Storage database](https://docs.phpmyadmin.net/en/latest/setup.html#phpmyadmin-configuration-storage). When [false](https://docs.phpmyadmin.net/en/latest/config.html#cfg_QueryHistoryDB), history is stored in the browser and is cleared when logging out
- `PMA_QUERYHISTORYMAX` - when set to an integer, controls the number of history items. See [documentation](https://docs.phpmyadmin.net/en/latest/config.html#cfg_QueryHistoryMax). Defaults to `25`.
- `MAX_EXECUTION_TIME` - if set, will override the maximum execution time in seconds (default 600) for phpMyAdmin ([$cfg['ExecTimeLimit']](https://docs.phpmyadmin.net/en/latest/config.html#cfg_ExecTimeLimit)) and PHP [max_execution_time](https://www.php.net/manual/en/info.configuration.php#ini.max-execution-time) (format as `[0-9+]`)
- `MEMORY_LIMIT` - if set, will override the memory limit (default 512M) for phpMyAdmin ([$cfg['MemoryLimit']](https://docs.phpmyadmin.net/en/latest/config.html#cfg_MemoryLimit)) and PHP [memory_limit](https://www.php.net/manual/en/ini.core.php#ini.memory-limit) (format as `[0-9+](K,M,G)` where K is for Kilobytes, M for Megabytes, G for Gigabytes and 1K = 1024 bytes)
- `UPLOAD_LIMIT` - if set, this option will override the default value for apache and php-fpm (format as `[0-9+](K,M,G)` default value is 2048K, this will change `upload_max_filesize` and `post_max_size` values)
- `TZ` - if defined, this option will change the default PHP `date.timezone` from `UTC`. See [documentation](https://www.php.net/manual/en/timezones.php) for supported values.
- `HIDE_PHP_VERSION` - if defined, this option will hide the PHP version (`expose_php = Off`). Set to any value (such as `HIDE_PHP_VERSION=true`).
- `APACHE_PORT` - if defined, this option will change the default Apache port from `80` in case you want it to run on a different port like an unprivileged port. Set to any port value (such as `APACHE_PORT=8090`)
For usage with Docker secrets, appending `_FILE` to the `PMA_PASSWORD` environment variable is allowed (it overrides `PMA_PASSWORD` if it is set):
```sh
docker run --name phpmyadmin -d -e PMA_PASSWORD_FILE=/run/secrets/db_password.txt -p 8080:80 %%IMAGE%%
```
#### Variables that can store the file contents using `_BASE64`
- `PMA_SSL_CA`
- `PMA_SSL_CAS`
- `PMA_SSL_KEY`
- `PMA_SSL_KEYS`
- `PMA_SSL_CERT`
- `PMA_SSL_CERTS`
Also includes: `PMA_CONFIG_BASE64` or `PMA_USER_CONFIG_BASE64`.
For example, the variable would be named `PMA_SSL_CA_BASE64` and the value is the base64 encoded contents of the file.
#### Variables that can be read from a file using `_FILE`
- `MYSQL_ROOT_PASSWORD`
- `MYSQL_PASSWORD`
- `PMA_USER`
- `PMA_PASSWORD`
- `PMA_HOSTS`
- `PMA_HOST`
- `PMA_CONTROLHOST`
- `PMA_CONTROLUSER`
- `PMA_CONTROLPASS`
For more detailed documentation see https://docs.phpmyadmin.net/en/latest/setup.html#installing-using-docker
Please report any issues with the Docker container to https://github.com/phpmyadmin/docker/issues
Please report any issues with phpMyAdmin to https://github.com/phpmyadmin/phpmyadmin/issues
```
--------------------------------------------------------------------------------
/mongo/content.md:
--------------------------------------------------------------------------------
```markdown
# What is MongoDB?
MongoDB is a [free and open-source cross-platform document-oriented database](https://en.wikipedia.org/wiki/Document-oriented_database) program. Classified as a [NoSQL](https://en.wikipedia.org/wiki/NoSQL) database program, MongoDB uses [JSON](https://en.wikipedia.org/wiki/JSON)-like documents with [schemata](https://en.wikipedia.org/wiki/Database_schema). MongoDB is developed by [MongoDB Inc.](https://en.wikipedia.org/wiki/MongoDB_Inc.), and is published under a combination of the [Server Side Public License](https://www.mongodb.com/licensing/server-side-public-license) and the [Apache License](https://en.wikipedia.org/wiki/Apache_License).
First developed by the software company 10gen (now MongoDB Inc.) in October 2007 as a component of a planned platform as a service product, the company shifted to an open source development model in 2009, with 10gen offering commercial support and other services. Since then, MongoDB has been adopted as backend software by a number of major websites and services, including MetLife, Barclays, ADP, UPS, Viacom, and the New York Times, among others. MongoDB is the most popular NoSQL database system.
> [wikipedia.org/wiki/MongoDB](https://en.wikipedia.org/wiki/MongoDB)
%%LOGO%%
# Security
By default Mongo's configuration requires no authentication for access, even for the administrative user. It is highly recommended to set a root user name and password if you plan on exposing your Mongo instance to the internet. See the "`MONGO_INITDB_ROOT_USERNAME`, `MONGO_INITDB_ROOT_PASSWORD`" section below for instructions and the [MongoDB Security documentation](https://www.mongodb.com/docs/manual/security/) for a more complete treatment.
# How to use this image
## Start a `%%REPO%%` server instance
```console
$ docker run --name some-%%REPO%% -d %%IMAGE%%:tag
```
... where `some-%%REPO%%` is the name you want to assign to your container and `tag` is the tag specifying the MongoDB version you want. See the list above for relevant tags.
## Connect to MongoDB from another Docker container
The MongoDB server in the image listens on the standard MongoDB port, `27017`, so connecting via Docker networks will be the same as connecting to a remote `mongod`. The following example starts another MongoDB container instance and runs the `mongosh` (use `mongo` with `4.x` versions) command line client against the original MongoDB container from the example above, allowing you to execute MongoDB statements against your database instance:
```console
$ docker run -it --network some-network --rm %%IMAGE%% mongosh --host some-%%REPO%% test
```
... where `some-%%REPO%%` is the name of your original `mongo` container.
## %%COMPOSE%%
Run `docker compose up`, wait for it to initialize completely, and visit `http://localhost:8081` or `http://host-ip:8081` (as appropriate).
## Container shell access and viewing MongoDB logs
The `docker exec` command allows you to run commands inside a Docker container. The following command line will give you a bash shell inside your `%%IMAGE%%` container:
```console
$ docker exec -it some-%%REPO%% bash
```
The MongoDB Server log is available through Docker's container log:
```console
$ docker logs some-%%REPO%%
```
# Configuration
See the [MongoDB manual](https://docs.mongodb.com/manual/) for information on using and configuring MongoDB for things like replica sets and sharding.
## Customize configuration without configuration file
Most MongoDB configuration can be set through flags to `mongod`. The entrypoint of the image is created to pass its arguments along to `mongod`. See below an example of setting MongoDB to use a different [threading and execution model](https://docs.mongodb.com/manual/reference/program/mongod/#cmdoption-mongod-serviceexecutor) via `docker run`.
```console
$ docker run --name some-%%REPO%% -d %%IMAGE%% --serviceExecutor adaptive
```
And here is the same with a `compose.yaml` file
```yaml
services:
mongo:
image: %%IMAGE%%
command: --serviceExecutor adaptive
```
To see the full list of possible options, check the MongoDB manual on [`mongod`](https://docs.mongodb.com/manual/reference/program/mongod/) or check the `--help` output of `mongod`:
```console
$ docker run -it --rm %%IMAGE%% --help
```
## Setting WiredTiger cache size limits
By default Mongo will set the `wiredTigerCacheSizeGB` to a value proportional to the host's total memory regardless of memory limits you may have imposed on the container. In such an instance you will want to set the cache size to something appropriate, taking into account any other processes you may be running in the container which would also utilize memory.
Taking the examples above you can configure the cache size to use 1.5GB as:
```console
$ docker run --name some-%%REPO%% -d %%IMAGE%% --wiredTigerCacheSizeGB 1.5
```
See [the upstream "WiredTiger Options" documentation](https://docs.mongodb.com/manual/reference/program/mongod/#wiredtiger-options) for more details.
## Using a custom MongoDB configuration file
For a more complicated configuration setup, you can still use the MongoDB configuration file. `mongod` does not read a configuration file by default, so the `--config` option with the path to the configuration file needs to be specified. Create a custom configuration file and put it in the container by either creating a custom Dockerfile `FROM %%IMAGE%%` or mounting it from the host machine to the container. See the MongoDB manual for a full list of [configuration file](https://docs.mongodb.com/manual/reference/configuration-options/) options.
For example, `/my/custom/mongod.conf` is the path to the custom configuration file. Then start the MongoDB container like the following:
```console
$ docker run --name some-%%REPO%% -v /my/custom:/etc/mongo -d %%IMAGE%% --config /etc/mongo/mongod.conf
```
## Environment Variables
When you start the `%%REPO%%` image, you can adjust the initialization of the MongoDB instance by passing one or more environment variables on the `docker run` command line. Do note that none of the variables below will have any effect if you start the container with a data directory that already contains a database: any pre-existing database will always be left untouched on container startup.
### `MONGO_INITDB_ROOT_USERNAME`, `MONGO_INITDB_ROOT_PASSWORD`
These variables, used in conjunction, create a new user and set that user's password. This user is created in the `admin` [authentication database](https://docs.mongodb.com/manual/core/security-users/#user-authentication-database) and given [the role of `root`](https://docs.mongodb.com/manual/reference/built-in-roles/#root), which is [a "superuser" role](https://docs.mongodb.com/manual/core/security-built-in-roles/#superuser-roles).
The following is an example of using these two variables to create a MongoDB instance and then using the `mongosh` cli (use `mongo` with `4.x` versions) to connect against the `admin` authentication database.
```console
$ docker run -d --network some-network --name some-%%REPO%% \
-e MONGO_INITDB_ROOT_USERNAME=mongoadmin \
-e MONGO_INITDB_ROOT_PASSWORD=secret \
%%IMAGE%%
$ docker run -it --rm --network some-network %%IMAGE%% \
mongosh --host some-mongo \
-u mongoadmin \
-p secret \
--authenticationDatabase admin \
some-db
> db.getName();
some-db
```
Both variables are required for a user to be created. If both are present then MongoDB will start with authentication enabled (`mongod --auth`).
Authentication in MongoDB is fairly complex, so more complex user setup is explicitly left to the user via `/docker-entrypoint-initdb.d/` (see the *Initializing a fresh instance* and *Authentication* sections below for more details).
### `MONGO_INITDB_DATABASE`
This variable allows you to specify the name of a database to be used for creation scripts in `/docker-entrypoint-initdb.d/*.js` (see *Initializing a fresh instance* below). MongoDB is fundamentally designed for "create on first use", so if you do not insert data with your JavaScript files, then no database is created.
## Docker Secrets
As an alternative to passing sensitive information via environment variables, `_FILE` may be appended to the previously listed environment variables, causing the initialization script to load the values for those variables from files present in the container. In particular, this can be used to load passwords from Docker secrets stored in `/run/secrets/<secret_name>` files. For example:
```console
$ docker run --name some-%%REPO%% -e MONGO_INITDB_ROOT_PASSWORD_FILE=/run/secrets/mongo-root -d %%IMAGE%%
```
Currently, this is only supported for `MONGO_INITDB_ROOT_USERNAME` and `MONGO_INITDB_ROOT_PASSWORD`.
# Initializing a fresh instance
When a container is started for the first time it will execute files with extensions `.sh` and `.js` that are found in `/docker-entrypoint-initdb.d`. Files will be executed in alphabetical order. `.js` files will be executed by `mongosh` (`mongo` on versions below 6) using the database specified by the `MONGO_INITDB_DATABASE` variable, if it is present, or `test` otherwise. You may also switch databases within the `.js` script.
# Authentication
As noted above, authentication in MongoDB is fairly complex (although disabled by default). For details about how MongoDB handles authentication, please see the relevant upstream documentation:
- [`mongod --auth`](https://docs.mongodb.com/manual/reference/program/mongod/#cmdoption-mongod-auth)
- [Security > Authentication](https://docs.mongodb.com/manual/core/authentication/)
- [Security > Role-Based Access Control](https://docs.mongodb.com/manual/core/authorization/)
- [Security > Role-Based Access Control > Built-In Roles](https://docs.mongodb.com/manual/core/security-built-in-roles/)
- [Security > Enable Auth (tutorial)](https://docs.mongodb.com/manual/tutorial/enable-authentication/)
In addition to the `/docker-entrypoint-initdb.d` behavior documented above (which is a simple way to configure users for authentication for less complicated deployments), this image also supports `MONGO_INITDB_ROOT_USERNAME` and `MONGO_INITDB_ROOT_PASSWORD` for creating a simple user with [the role `root`](https://docs.mongodb.com/manual/reference/built-in-roles/#root) in the `admin` [authentication database](https://docs.mongodb.com/manual/core/security-users/#user-authentication-database), as described in the *Environment Variables* section above.
# Caveats
## Where to Store Data
Important note: There are several ways to store data used by applications that run in Docker containers. We encourage users of the `%%REPO%%` images to familiarize themselves with the options available, including:
- Let Docker manage the storage of your database data [by writing the database files to disk on the host system using its own internal volume management](https://docs.docker.com/storage/volumes/). This is the default and is easy and fairly transparent to the user. The downside is that the files may be hard to locate for tools and applications that run directly on the host system, i.e. outside containers.
- Create a data directory on the host system (outside the container) and [mount this to a directory visible from inside the container](https://docs.docker.com/storage/bind-mounts/). This places the database files in a known location on the host system, and makes it easy for tools and applications on the host system to access the files. The downside is that the user needs to make sure that the directory exists, and that e.g. directory permissions and other security mechanisms on the host system are set up correctly.
**WARNING (Windows & OS X)**: When running the Linux-based MongoDB images on Windows and OS X, the file systems used to share between the host system and the Docker container is not compatible with the memory mapped files used by MongoDB ([docs.mongodb.org](https://docs.mongodb.com/manual/administration/production-notes/#fsync---on-directories) and related [jira.mongodb.org](https://jira.mongodb.org/browse/SERVER-8600) bug). This means that it is not possible to run a MongoDB container with the data directory mapped to the host. To persist data between container restarts, we recommend using a local named volume instead (see `docker volume create`). Alternatively you can use the Windows-based images on Windows.
The Docker documentation is a good starting point for understanding the different storage options and variations, and there are multiple blogs and forum postings that discuss and give advice in this area. We will simply show the basic procedure here for the latter option above:
1. Create a data directory on a suitable volume on your host system, e.g. `/my/own/datadir`.
2. Start your `%%REPO%%` container like this:
```console
$ docker run --name some-%%REPO%% -v /my/own/datadir:/data/db -d %%IMAGE%%
```
The `-v /my/own/datadir:/data/db` part of the command mounts the `/my/own/datadir` directory from the underlying host system as `/data/db` inside the container, where MongoDB by default will write its data files.
This image also defines a volume for `/data/configdb` [for use with `--configsvr` (see docs.mongodb.com for more details)](https://docs.mongodb.com/v3.4/reference/program/mongod/#cmdoption-configsvr).
## Creating database dumps
Most of the normal tools will work, although their usage might be a little convoluted in some cases to ensure they have access to the `mongod` server. A simple way to ensure this is to use `docker exec` and run the tool from the same container, similar to the following:
```console
$ docker exec some-%%REPO%% sh -c 'exec mongodump -d <database_name> --archive' > /some/path/on/your/host/all-collections.archive
```
```
--------------------------------------------------------------------------------
/open-liberty/content.md:
--------------------------------------------------------------------------------
```markdown
# Overview
All of the images in this repository use Ubuntu as the Operating System. For variants that use the Universal Base Image, please see [this repository](https://hub.docker.com/r/openliberty/open-liberty/).
For more information on these images please see our [GitHub repository](https://github.com/OpenLiberty/ci.docker#container-images).
# Image User
This image runs by default with `USER 1001` (non-root), as part of group `0`. Please make sure you read below to set the appropriate folder and file permissions.
## Updating folder permissions
All of the folders accessed by Open Liberty have been given the appropriate permissions, but if your extending Dockerfile needs permission to another location you can simply temporarily switch into root and provide the needed permissions, example:
```dockerfile
USER root
RUN mkdir -p /myFolder && chown -R 1001:0 /myFolder
USER 1001
```
## Updating file permissions
You have to make sure that **all** the artifacts you are copying into the image (via `COPY` or `ADD`) have the correct permissions to be `read` and `executed` by user `1001` or group `0`, because the ownership of the file is changed to be `root:0` when transferring into the docker image.
You have a few options for doing this: before copying the file, during copy, or after copy.
### Updating permissions before copying
Since the ownership of the file will change to `root:0`, you can simply set the permissions for the owner's group to be able to read/execute the artifact (i.e. the middle digit of a `chmod` command). For example, you can do `chmod g+rx server.xml` to ensure your `server.xml` can be `read` and `executed` by group `0`, as well as any artifacts such as the application's `EAR` or `WAR` file, JDBC driver, or other files that are placed on the image via `COPY` or `ADD`.
### Updating permissions during copy
If you're using Docker v17.09.0-ce and newer you can take advantage of the flag `--chown=<user>:<group>` during either `ADD` or `COPY`. For example: `COPY --chown=1001:0 jvm.options /config/jvm.options`. This is the preferred approach as you don't need to worry about changing permissions before calling `docker build` and you also do not duplicate layers in the resulting image.
### Updating permissions after copy
If you need your Dockerfile to work with older versions of Docker CE and don't want to pre-process the permissions of the files you can temporarily switch into root to change the permissions of the needed files. For example:
```dockerfile
USER root
RUN chown 1001:0 /config/jvm.options
RUN chown 1001:0 /output/resources/security/ltpa.keys
USER 1001
```
Please note that this pattern will duplicate the docker layers for those artifacts, which can heavily bloat your resulting docker image (depending on the size of the artifact). So it is recommended to set the permissions before or during copy.
## Tags
There are multiple tags available in this repository.
The `kernel-slim` image contains just the Liberty kernel and no additional runtime features. This image is the recommended basis for custom built images, so that they can contain only the features required for a specific application. For example, the following Dockerfile starts with this image, copies in the `server.xml` that lists the features required by the application, and then uses the `features.sh` script to download those features from the online repository.
```dockerfile
FROM %%IMAGE%%:kernel-slim
# Add server configuration
COPY --chown=1001:0 server.xml /config/
# This script will add the requested XML snippets to enable Liberty features and grow image to be fit-for-purpose using featureUtility.
# Only available in 'kernel-slim'. The 'full' tag already includes all features for convenience.
RUN features.sh
# Add the application
COPY --chown=1001:0 Sample1.war /config/dropins/
# This script will add the requested server configurations, apply any interim fixes and populate caches to optimize runtime.
RUN configure.sh
```
The full list of images are found in the `Supported tags and respective Dockerfile links` section above.
# Usage
The images are designed to support a number of different usage patterns. The following examples are based on the Java EE8 Liberty [application deployment sample](https://developer.ibm.com/wasdev/docs/article_appdeployment/) and assume that [DefaultServletEngine.zip](https://github.com/WASdev/sample.servlet/releases/download/V1/DefaultServletEngine.zip) has been extracted to `/tmp` and the `server.xml` updated to accept HTTP connections from outside of the container by adding the following element inside the `server` stanza (if not using one of the pre-packaged `server.xml` files with our tags):
```xml
<httpEndpoint host="*" httpPort="9080" httpsPort="-1"/>
```
## Application Image
It is a very strong best practice to create an extending Docker image, we called it the `application image`, that encapsulates an application and its configuration. This creates a robust, self-contained and predictable Docker image that can span new containers upon request, without relying on volumes or other external runtime artifacts that may behave different over time.
If you want to build the smallest possible Open Liberty application image you can start with our `kernel` tag, add your artifacts, and run `configure.sh` to grow the set of features to be fit-for-purpose. Please see our [GitHub page](https://github.com/OpenLiberty/ci.docker#building-an-application-image) for more details.
## Enabling Enterprise functionality
The Open Liberty images have a set of built-in XML snippets that enable and configure enterprise functionality such as session cache and monitoring. These are toggled by specific `ARG`s in your application image Dockerfile and configured via the `configure.sh` script. Please see the [instructions](https://github.com/openliberty/ci.docker#enterprise-functionality) on our GitHub page for more information.
## Using volumes for configuration
This pattern can be useful for quick experiments / early development (i.e. `I just want to run the application as I iterate over it`), but should not be used for development scenarios that involve different teams and environments - for these cases the `Application Image` pattern described above is the way to go.
When using `volumes`, an application file can be mounted in the `dropins` directory of this server and run. The following example starts a container in the background running a .WAR file from the host file system with the HTTP and HTTPS ports mapped to 80 and 443 respectively.
```console
$ docker run -d -p 80:9080 -p 443:9443 \
-v /tmp/DefaultServletEngine/dropins/Sample1.war:/config/dropins/Sample1.war \
%%IMAGE%%:full
```
When the server is started, you can browse to http://localhost/Sample1/SimpleServlet on the Docker host.
Note: If you are using the boot2docker virtual machine on OS X or Windows, you need to get the IP of the virtual host by using the command `boot2docker ip` instead of by using localhost.
For greater flexibility over configuration, it is possible to mount an entire server configuration directory from the host and then specify the server name as a parameter to the run command. Note: This particular example server configuration provides only HTTP access.
```console
$ docker run -d -p 80:9080 \
-v /tmp/DefaultServletEngine:/config \
%%IMAGE%%:full
```
# Using Spring Boot with Open Liberty
The `full` images introduce capabilities specific to the support of all Liberty features, including Spring Boot applications. This image thus includes the `springBootUtility` used to separate Spring Boot applications into thin applications and dependency library caches. To get these same capabilities without including features you are not using, build instead on top of `kernel` images and run configure.sh for your server.xml, ensuring that it enables either the `springBoot-1.5` or `springBoot-2.0` feature.
To elaborate these capabilities this section assumes the standalone Spring Boot 2.0.x application `hellospringboot.jar` exists in the `/tmp` directory.
1. A Spring Boot application JAR deploys to the `dropins/spring` directory within the default server configuration, not the `dropins` directory. Liberty allows one Spring Boot application per server configuration. You can create a Spring Boot application layer over this image by adding the application JAR to the `dropins/spring` directory. In this example we copied `hellospringboot.jar` from `/tmp` to the same directory containing the following Dockerfile.
```dockerfile
FROM %%IMAGE%%:kernel
COPY --chown=1001:0 hellospringboot.jar /config/dropins/spring/
COPY --chown=1001:0 server.xml /config/
RUN configure.sh
```
The custom image can be built and run as follows.
```console
$ docker build -t app .
$ docker run -d -p 8080:9080 app
```
2. The `full` images provide the library cache directory, `lib.index.cache`, which contains an indexed library cache created by the `springBootUtility` command. Use `lib.index.cache` to provide the library cache for a thin application.
You can use the `springBootUtility` command to create thin application and library cache layers over a `full` image. The following example uses docker staging to efficiently build an image that deploys a fat Spring Boot application as two layers containing a thin application and a library cache.
```dockerfile
FROM %%IMAGE%%:kernel as staging
COPY --chown=1001:0 hellospringboot.jar /staging/myFatApp.jar
COPY --chown=1001:0 server.xml /config/
RUN springBootUtility thin \
--sourceAppPath=/staging/myFatApp.jar \
--targetThinAppPath=/staging/myThinApp.jar \
--targetLibCachePath=/staging/lib.index.cache
FROM %%IMAGE%%:kernel
COPY --chown=1001:0 server.xml /config
COPY --from=staging /staging/lib.index.cache /lib.index.cache
COPY --from=staging /staging/myThinApp.jar /config/dropins/spring/myThinApp.jar
RUN configure.sh
```
For Spring Boot applications packaged with library dependencies that rarely change across continuous application updates, you can use the capabilities mentioned above to to share library caches across containers and to create even more efficient docker layers that leverage the docker build cache.
# Providing your own keystore/truststore
When an `open-liberty` image starts, it can generate a Liberty server XML snippet in `/config/configDropins/defaults/keystore.xml` that specifies a `keyStore` stanza with a generated password. This causes Open Liberty to generate a default keystore and truststore with a self-signed certificate when it starts. Images can request this by setting:
```console
ENV KEYSTORE_REQUIRED "true"
```
When providing your own keystore/truststore, this default behavior can be disabled by adding:
```console
ENV KEYSTORE_REQUIRED "false"
```
It is good practice to place the keystore customization in `/config/configDropins/defaults/keystore.xml` even when not generated since this makes it easier to find and makes moving to the websphere-liberty docker image simpler.
# Using IBM JRE Class data sharing
The IBM JRE provides a feature [Class data sharing](http://www-01.ibm.com/support/knowledgecenter/SSYKE2_8.0.0/com.ibm.java.lnx.80.doc/diag/understanding/shared_classes.html) which offers transparent and dynamic sharing of data between multiple Java Virtual Machines running on the same host by using shared memory backed by a file. When running the Liberty Docker image, it looks for the file at `/opt/ol/wlp//output/.classCache`. To benefit from Class data sharing, this location needs to be shared between containers either through the host or a data volume container.
Taking the application image from example 3 above, containers can share the host file location (containing the shared cache) `/tmp/open-liberty/classCache` as follows:
```console
docker run -d -p 80:9080 -p 443:9443 \
-v /tmp/open-liberty/classCache:/opt/ol/wlp/output/.classCache app
```
Or, create a named data volume container that exposes a volume at the location of the shared file:
```console
docker run -v /opt/ol/wlp//output/.classCache \
--name classcache %%IMAGE%% true
```
Then, run the Open Liberty image with the volumes from the data volume container classcache mounted as follows:
```console
docker run -d -p 80:9080 -p 443:9443 --volumes-from classcache app
```
# Running Open Liberty in read-only mode
Liberty writes to two different directories when running: `/opt/ol/wlp//output` and `/logs`. In order to run the Liberty image in read-only mode these may be mounted as temporary file systems. If using the provided image, the keystore will be generated on initial start up in the server configuration. This means that the server configuration directory either needs to be read-write or the keystore will need to be built into the image. In the example command `/config` is mounted as a read-write volume.
```console
docker run -d -p 80:9080 -p 443:9443 \
--tmpfs /opt/ol/wlp//output --tmpfs /logs -v /config --read-only \
%%IMAGE%%:webProfile8
```
# Relationship between Open Liberty and WebSphere Liberty
WebSphere Liberty is a commercial distribution of Open Liberty. There is an official docker image for websphere-liberty. The websphere-liberty docker image predates the open-liberty one, so to make it simpler to move from open-liberty to websphere-liberty (or vice versa) the images are broadly compatible. It should be possible to move from one to the other with a simple FROM clause change. Some considerations for moving between them:
- Open Liberty installs into `/opt/ol` rather than `/opt/ibm`.
- Use the `/config` folder for accessing the server configuration.
- Use the `/output` folder for accessing the server output.
- When adding your own SSL configuration use the `/config/configDropins/defaults/keystore.xml`.
```
--------------------------------------------------------------------------------
/ros/content.md:
--------------------------------------------------------------------------------
```markdown
# What is [ROS](https://www.ros.org/)?
The Robot Operating System (ROS) is a set of software libraries and tools that help you build robot applications. From drivers to state-of-the-art algorithms, and with powerful developer tools, ROS has what you need for your next robotics project. And it's all open source.
> [wikipedia.org/wiki/Robot_Operating_System](https://en.wikipedia.org/wiki/Robot_Operating_System)
[%%LOGO%%](https://www.ros.org/)
# How to use this image
## Creating a `Dockerfile` to install ROS packages
To create your own ROS docker images and install custom packages, here's a simple example of installing the C++, Python client library demos using the official released Debian packages via apt-get.
```dockerfile
FROM %%IMAGE%%:foxy
# install ros package
RUN apt-get update && apt-get install -y \
ros-${ROS_DISTRO}-demo-nodes-cpp \
ros-${ROS_DISTRO}-demo-nodes-py && \
rm -rf /var/lib/apt/lists/*
# launch ros package
CMD ["ros2", "launch", "demo_nodes_cpp", "talker_listener_launch.py"]
```
Note: all ROS images include a default entrypoint that sources the ROS environment setup before executing the configured command, in this case the demo packages launch file. You can then build and run the Docker image like so:
```console
$ docker build -t my/ros:app .
$ docker run -it --rm my/ros:app
[INFO] [launch]: process[talker-1]: started with pid [813]
[INFO] [launch]: process[listener-2]: started with pid [814]
[INFO] [talker]: Publishing: 'Hello World: 1'
[INFO] [listener]: I heard: [Hello World: 1]
[INFO] [talker]: Publishing: 'Hello World: 2'
[INFO] [listener]: I heard: [Hello World: 2]
...
```
## Creating a `Dockerfile` to build ROS packages
To create your own ROS docker images and build custom packages, here's a simple example of installing a package's build dependencies, compiling it from source, and installing the resulting build artifacts into a final multi-stage image layer.
```dockerfile
ARG FROM_IMAGE=%%IMAGE%%:foxy
ARG OVERLAY_WS=/opt/ros/overlay_ws
# multi-stage for caching
FROM $FROM_IMAGE AS cacher
# clone overlay source
ARG OVERLAY_WS
WORKDIR $OVERLAY_WS/src
RUN echo "\
repositories: \n\
ros2/demos: \n\
type: git \n\
url: https://github.com/ros2/demos.git \n\
version: ${ROS_DISTRO} \n\
" > ../overlay.repos
RUN vcs import ./ < ../overlay.repos
# copy manifests for caching
WORKDIR /opt
RUN mkdir -p /tmp/opt && \
find ./ -name "package.xml" | \
xargs cp --parents -t /tmp/opt && \
find ./ -name "COLCON_IGNORE" | \
xargs cp --parents -t /tmp/opt || true
# multi-stage for building
FROM $FROM_IMAGE AS builder
# install overlay dependencies
ARG OVERLAY_WS
WORKDIR $OVERLAY_WS
COPY --from=cacher /tmp/$OVERLAY_WS/src ./src
RUN . /opt/ros/$ROS_DISTRO/setup.sh && \
apt-get update && rosdep install -y \
--from-paths \
src/ros2/demos/demo_nodes_cpp \
src/ros2/demos/demo_nodes_py \
--ignore-src \
&& rm -rf /var/lib/apt/lists/*
# build overlay source
COPY --from=cacher $OVERLAY_WS/src ./src
ARG OVERLAY_MIXINS="release"
RUN . /opt/ros/$ROS_DISTRO/setup.sh && \
colcon build \
--packages-select \
demo_nodes_cpp \
demo_nodes_py \
--mixin $OVERLAY_MIXINS
# source entrypoint setup
ENV OVERLAY_WS $OVERLAY_WS
RUN sed --in-place --expression \
'$isource "$OVERLAY_WS/install/setup.bash"' \
/ros_entrypoint.sh
# run launch file
CMD ["ros2", "launch", "demo_nodes_cpp", "talker_listener_launch.py"]
```
The example above starts by using [`vcstool`](https://github.com/dirk-thomas/vcstool) to clone source repos of interest into the cacher stage. One could similarly `COPY` code from the local build context into the source directory as well. Package manifest files are then cached in a temporary directory where the following builder stage may copy from to install necessary dependencies with [`rosdep`](https://github.com/ros-infrastructure/rosdep). This is done prior to copying the rest of the source files to preserve the multi-stage build cache, given unaltered manifests do not alter declared dependencies, saving time and bandwidth. The overlay is then built using [`colcon`](https://colcon.readthedocs.io/en/released/), the entrypoint updated to source the workspace, and the default command set to launch the demo.
Note: `--from-paths` and `--packages-select` are set here as so to only install the dependencies and build for the demo C++ and Python packages, among many in the demo git repo that was cloned. To install the dependencies and build all the packages in the source workspace, merely change the scope by setting `--from-paths src/` and dropping the `--packages-select` arguments.
For more advance examples such as daisy chaining multiple overlay workspaces to improve caching of docker image build layers, using tools such as ccache to accelerate compilation with colcon, or using buildkit to save build time and bandwidth even when dependencies change, the project `Dockerfile`s in the ROS 2 [Navigation2](https://github.com/ros-planning/navigation2) repo are excellent resources.
## Deployment use cases
This dockerized image of ROS is intended to provide a simplified and consistent platform to build and deploy distributed robotic applications. Built from the [official Ubuntu image](https://hub.docker.com/_/ubuntu/) and ROS's official Debian packages, it includes recent supported releases for quick access and download. This provides roboticists in research and industry with an easy way to develop, reuse and ship software for autonomous actions and task planning, control dynamics, localization and mapping, swarm behavior, as well as general system integration.
Developing such complex systems with cutting edge implementations of newly published algorithms remains challenging, as repeatability and reproducibility of robotic software can fall to the wayside in the race to innovate. With the added difficulty in coding, tuning and deploying multiple software components that span across many engineering disciplines, a more collaborative approach becomes attractive. However, the technical difficulties in sharing and maintaining a collection of software over multiple robots and platforms has for a while exceeded time and effort than many smaller labs and businesses could afford.
With the advancements and standardization of software containers, roboticists are primed to acquire a host of improved developer tooling for building and shipping software. To help alleviate the growing pains and technical challenges of adopting new practices, we have focused on providing an official resource for using ROS with these new technologies.
For a complete listing of supported architectures and base images for each ROS Distribution Release, please read the official REP on target platforms for either [ROS 1](https://www.ros.org/reps/rep-0003.html) or for [ROS 2](https://www.ros.org/reps/rep-2000.html).
## Deployment suggestions
The available tags include supported distros along with a hierarchy tags based off the most common meta-package dependencies, designed to have a small footprint and simple configuration:
- `ros-core`: minimal ROS install
- `ros-base`: basic tools and libraries (also tagged with distro name with LTS version as `latest`)
- `ros1-bridge`: tools and libraries to run hybrid ROS 1 - ROS 2 systems and bridge messages between them
In the interest of keeping `ros-core` tag minimal in image size, developer tools such as `rosdep`, `colcon` and `vcstools` are not shipped in `ros_core`, but in `ros-base` instead.
The rest of the common meta-packages such as `desktop` are hosted on repos under OSRF's Docker Hub profile [here](https://hub.docker.com/r/osrf/ros/). These meta-packages include graphical dependencies and hook a host of other large packages such as X11, X server, etc. So in the interest of keeping the official images lean and secure, the desktop packages are just being hosted with OSRF's profile. For an extensive list of available variants, please read the official REP on target platforms for either [ROS 1](https://ros.org/reps/rep-0150.html) or for [ROS 2](https://www.ros.org/reps/rep-2001.html).
### Volumes
ROS uses the `~/.ros/` directory for storing logs, and debugging info. If you wish to persist these files beyond the lifecycle of the containers which produced them, the `~/.ros/` folder can be mounted to an external volume on the host, or a derived image can specify volumes to be managed by the Docker engine. By default, the container runs as the `root` user, so `/root/.ros/` would be the full path to these files.
For example, if one wishes to use their own `.ros` folder that already resides in their local home directory, with a username of `ubuntu`, we can simply launch the container with an additional volume argument:
```console
$ docker run -v "/home/ubuntu/.ros/:/root/.ros/" %%IMAGE%%
```
### Devices
Some application may require device access for acquiring images from connected cameras, control input from human interface device, or GPUS for hardware acceleration. This can be done using the [`--device`](https://docs.docker.com/engine/reference/commandline/run/#add-host-device-to-container---device) run argument to mount the device inside the container, providing processes inside hardware access.
### Networks
ROS allows for peer-to-peer networking of processes (potentially distributed across machines) that are loosely coupled using the ROS communication infrastructure. ROS implements several different styles of communication, including synchronous RPC-style communication over services, asynchronous streaming of typed data over topics, combinations of both prior via request/reply and status/feedback over actions, and run-time settings via configuration over parameters. To abide by the best practice of [one process per container](https://docs.docker.com/articles/dockerfile_best-practices/), Docker networks can be used to string together several running ROS processes. For further details see the Deployment example further below.
Alternatively, more permissive network settings can be used to share all host network interfaces with the container, such as [`host` network driver](https://docs.docker.com/network/host/), simplifying connectivity with external network participants. Be aware however that this removes the networking namespace separation between containers, and can affect the ability of DDS participants to communicate between containers, as documented [here](https://community.rti.com/kb/how-use-rti-connext-dds-communicate-across-docker-containers-using-host-driver).
## Deployment example
### Docker Compose
In this example we'll demonstrate using [`docker compose`](https://docs.docker.com/compose/) to spawn a pair of message publisher and subscriber nodes in separate containers connected through shared software defined network.
> Create the directory `~/ros_demos` and add the first `Dockerfile` example from above. In the same directory, also create file `compose.yaml` with the following that runs a C++ publisher with a Python subscriber:
```yaml
services:
talker:
build: ./
command: ros2 run demo_nodes_cpp talker
listener:
build: ./
environment:
- "PYTHONUNBUFFERED=1"
command: ros2 run demo_nodes_py listener
```
> Use `docker compose` inside the same directory to launch our ROS nodes. Given the containers created derive from the same docker compose project, they will coexist on shared project network:
```console
$ docker compose up -d
```
> Notice that a new network named `ros_demos_default` has been created, as can be shown further with:
```console
$ docker network inspect ros_demos_default
```
> We can monitor the logged output of each container, such as the listener node like so:
```console
$ docker compose logs listener
```
> Finally, we can stop and remove all the relevant containers using `docker compose` from the same directory:
```console
$ docker compose stop
$ docker compose rm
```
> Note: the auto-generated network, `ros_demos_default`, will persist until you explicitly remove it using `docker compose down`.
### ROS 1 Bridge
To ease ROS 2 migration, [`ros1_bridge`](https://index.ros.org/p/ros1_bridge) is a ROS 2 package that provides bidirectional communication between ROS 1 and ROS 2. As a minimal example, given the ROS 2 Dockerfile above, we'll create the ROS 1 equivalent below, and name the Dockerfile appropriately.
```dockerfile
FROM %%IMAGE%%:noetic
# install ros package
RUN apt-get update && apt-get install -y \
ros-${ROS_DISTRO}-ros-tutorials \
ros-${ROS_DISTRO}-common-tutorials && \
rm -rf /var/lib/apt/lists/*
# launch ros package
CMD ["roslaunch", "roscpp_tutorials", "talker_listener_launch"]
```
The compose file bellow spawns services for both talker listener demos while connecting the two via a dynamic bridge. You may then view the log output from both pairs of talker and listener nodes cross talking over the `/chatter` topic.
```yaml
services:
ros1:
build:
context: ./
dockerfile: ros1.Dockerfile
ros2:
build:
context: ./
dockerfile: ros2.Dockerfile
bridge:
image: ros:foxy-ros1-bridge
environment:
- "ROS_HOSTNAME=bridge"
- "ROS_MASTER_URI=http://ros1:11311"
command: ros2 run ros1_bridge dynamic_bridge
```
# More Resources
[ROS.org](http://www.ros.org/): Main ROS website
[Q&A](https://answers.ros.org/questions/): Ask questions. Get answers
[Forums](https://discourse.ros.org/): Hear the latest discussions
[Blog](http://www.ros.org/news/): Stay up-to-date
[Packages](https://index.ros.org/?search_packages=true): Discover indexed packages
[OSRF](https://www.osrfoundation.org/): Open Source Robotics Foundation
## ROS 2
[Index](https://docs.ros.org): ROS 2 Documentation
[Design](https://design.ros2.org/): ROS 2 Design Articles
## ROS 1
[Wiki](http://wiki.ros.org/Documentation): ROS 1 Documentation
```
--------------------------------------------------------------------------------
/yourls/logo.svg:
--------------------------------------------------------------------------------
```
<svg width="256" height="105" viewBox="0 0 512 210" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink"><defs><path d="M24.896 15.55h23.08c1.601 0 2.9-1.3 2.9-2.905a2.903 2.903 0 00-2.9-2.906h-23.08c-1.602 0-2.9 1.3-2.9 2.906a2.903 2.903 0 002.9 2.905z" id="a"/><path id="b" d="M35.515 15.726H3v14.026h32.515v15.726L59.954 22.74 35.514 0z"/></defs><g fill="none" fill-rule="evenodd"><path d="M121.616 119.57a64.31 64.31 0 01-7.095 8.91 49.85 49.85 0 01-15.462 25.467 49.586 49.586 0 01-32.864 12.399 49.639 49.639 0 01-32.886-12.412 49.755 49.755 0 01-15.46-25.481 64.31 64.31 0 01-7.07-8.883C3.63 108.748-.034 96.074.054 82.762L.16 65.697c.099-27.418 22.356-49.599 49.78-49.599 5.576 0 11.063.929 16.258 2.723a49.777 49.777 0 0116.257-2.723c27.425 0 49.682 22.18 49.781 49.599l.106 17.065c.087 13.312-3.576 25.986-10.726 36.808zm28.233 28.606c-36.428 0-65.959-29.531-65.959-65.96 0-36.428 29.53-65.959 65.96-65.959 36.427 0 65.958 29.531 65.958 65.96 0 36.428-29.53 65.959-65.959 65.959zm99.855-131.919c27.406 0 49.622 22.217 49.622 49.622v16.31c0 36.433-29.608 65.933-66.092 65.933-36.483 0-66.092-29.5-66.092-65.932V65.88c0-27.406 22.217-49.623 49.622-49.623 5.654 0 11.215.958 16.47 2.807a49.615 49.615 0 0116.47-2.807zm49.463 131.812c-27.408 0-49.622-22.218-49.622-49.633l.004-16.642c.678-36.01 29.399-64.848 65.143-65.525a66.91 66.91 0 011.266-.012h11.845c27.406 0 49.622 22.217 49.622 49.622a49.47 49.47 0 01-11.534 31.809 49.701 49.701 0 01-18.875 13.953c-5.793 21.075-25.098 36.428-47.85 36.428zM377.957 0c27.405 0 49.622 22.217 49.622 49.622V98.47c0 27.426-22.207 49.652-49.622 49.652-27.406 0-49.623-22.216-49.623-49.622V49.622C328.334 22.217 350.551 0 377.957 0zm73.158 148.282h-21.73c-27.494 0-49.781-22.29-49.781-49.785 0-3.753.42-7.475 1.248-11.103a49.864 49.864 0 01-.825-17.584c3.618-30.603 29.596-53.712 60.462-53.712h21.73c27.494 0 49.78 22.29 49.78 49.785 0 3.753-.42 7.475-1.248 11.102a49.864 49.864 0 01.826 17.585c-3.619 30.603-29.597 53.712-60.462 53.712z" fill="#4393BB" fill-rule="nonzero"/><path d="M118.104 82.853c.07 10.485-2.772 20.399-8.367 28.868a50.206 50.206 0 01-8.334 9.667c-2.393 17.373-17.218 30.718-35.207 30.72-17.998-.002-32.87-13.38-35.218-30.733a50.205 50.205 0 01-8.319-9.654c-5.596-8.469-8.436-18.383-8.367-28.868l.106-17.088c.062-19.58 15.955-35.429 35.543-35.429a35.47 35.47 0 0116.257 3.93 35.47 35.47 0 0116.257-3.93c19.588 0 35.48 15.848 35.543 35.43l.106 17.087zm31.745 51.084c-28.564 0-51.72-23.156-51.72-51.72 0-28.565 23.156-51.721 51.72-51.721 28.565 0 51.72 23.156 51.72 51.72 0 28.565-23.155 51.721-51.72 51.721zm99.855-103.441c19.542 0 35.384 15.842 35.384 35.383v16.31c0 28.572-23.236 51.695-51.854 51.695-28.617 0-51.853-23.123-51.853-51.694V65.88c0-19.542 15.842-35.384 35.384-35.384a35.313 35.313 0 0116.47 4.06 35.311 35.311 0 0116.47-4.06zm49.463 103.335c-19.543 0-35.384-15.843-35.384-35.391l.005-16.51c.532-28.257 23.116-50.894 51.174-51.425.332-.006.664-.01.996-.01h11.845c19.542 0 35.384 15.843 35.384 35.384 0 17.258-12.355 31.63-28.703 34.754-1.129 18.524-16.51 33.198-35.317 33.198zm78.79-119.593c19.541 0 35.383 15.842 35.383 35.384V98.47c0 19.565-15.834 35.414-35.383 35.414-19.542 0-35.384-15.842-35.384-35.384V49.622c0-19.542 15.842-35.384 35.384-35.384zm119.805 73.85c0 1.58-.105 3.156-.314 4.719-2.728 23.461-22.634 41.236-46.333 41.236h-21.73c-19.63 0-35.543-15.915-35.543-35.546 0-3.817.607-7.556 1.772-11.103a35.53 35.53 0 01-1.772-11.101c0-1.58.105-3.157.314-4.72 2.728-23.461 22.633-41.237 46.333-41.237h21.73c19.63 0 35.543 15.916 35.543 35.547 0 3.816-.607 7.556-1.772 11.102a35.53 35.53 0 011.772 11.102z" fill="#FFF" fill-rule="nonzero"/><path d="M481.64 76.986a22.265 22.265 0 012.946 11.101c0 1.034-.071 2.064-.213 3.082-1.9 16.838-16.17 29.698-33.258 29.698h-21.73c-12.354 0-22.367-10.017-22.367-22.37 0-4.04 1.071-7.831 2.945-11.103a22.265 22.265 0 01-2.945-11.101c0-1.034.071-2.064.212-3.082 1.9-16.839 16.17-29.699 33.259-29.699h21.73c12.354 0 22.367 10.017 22.367 22.37 0 4.041-1.071 7.832-2.945 11.104z" fill="#4393BB" fill-rule="nonzero"/><path d="M454.09 88.087a8.129 8.129 0 1116.156 1.285c-.992 9.694-9.179 17.257-19.131 17.257h-21.73a8.13 8.13 0 01-8.129-8.132 8.13 8.13 0 018.13-8.132h22.42c1.258 0 2.28-1.02 2.284-2.278zm-16.576-11.794a8.129 8.129 0 11-16.157-1.285c.993-9.695 9.18-17.257 19.132-17.257h21.73a8.13 8.13 0 018.128 8.132 8.13 8.13 0 01-8.128 8.132h-22.42a2.285 2.285 0 00-2.285 2.278z" fill="#FFF"/><path d="M355.749 49.622c0-12.265 9.943-22.208 22.208-22.208 12.265 0 22.207 9.943 22.207 22.208V98.47c0 12.295-9.942 22.238-22.207 22.238s-22.208-9.943-22.208-22.208V49.622z" fill="#4393BB" fill-rule="nonzero"/><path d="M369.828 49.622a8.129 8.129 0 1116.257 0V98.5a8.129 8.129 0 11-16.257-.053V49.622z" fill="#FFF"/><path d="M321.375 98.448c0 12.265-9.943 22.207-22.208 22.207-12.265 0-22.208-9.943-22.208-22.212l.005-16.388c.397-21.079 17.298-37.98 38.247-38.376.249-.005.498-.007.747-.007h11.845c12.265 0 22.208 9.942 22.208 22.207s-9.943 22.208-22.208 22.208h-6.427l-.001 10.361z" fill="#4393BB" fill-rule="nonzero"/><path d="M307.296 98.447l.001-16.257a8.182 8.182 0 018.183-8.182h12.323a8.129 8.129 0 100-16.257h-11.845c-.16 0-.32.001-.48.004-13.383.254-24.188 11.027-24.44 24.408v16.284a8.129 8.129 0 0016.258 0z" fill="#FFF"/><g><path d="M249.704 43.672c12.265 0 22.208 9.942 22.208 22.207v16.31c0 21.294-17.337 38.52-38.678 38.52-21.34 0-38.677-17.226-38.677-38.52V65.88c0-12.265 9.943-22.207 22.208-22.207 6.532 0 12.406 2.82 16.47 7.31 4.063-4.49 9.937-7.31 16.47-7.31z" fill="#4393BB" fill-rule="nonzero"/><path d="M241.576 82.19h-.006a8.341 8.341 0 01-16.67 0l-.007-16.31a8.129 8.129 0 10-16.257 0v16.31c0 13.497 11.013 24.439 24.598 24.439 13.586 0 24.599-10.942 24.599-24.44V65.88a8.129 8.129 0 00-16.257 0v16.31z" fill="#FFF"/></g><g><path d="M149.85 120.761c-21.289 0-38.546-17.257-38.546-38.545 0-21.287 17.257-38.544 38.545-38.544s38.545 17.257 38.545 38.544c0 21.288-17.257 38.545-38.545 38.545z" fill="#4393BB" fill-rule="nonzero"/><path d="M149.85 106.523c-13.425 0-24.307-10.883-24.307-24.307s10.882-24.306 24.306-24.306c13.424 0 24.306 10.882 24.306 24.306 0 13.424-10.882 24.307-24.306 24.307zm.026-16.204a8.129 8.129 0 100-16.258 8.129 8.129 0 000 16.258z" fill="#FFF"/></g><g><path d="M82.455 43.512c12.335 0 22.337 9.985 22.367 22.313l.106 17.113c.053 7.883-2.037 15.242-6.184 21.52-2.704 4.091-6.145 7.533-10.18 10.299v1.686c0 12.473-10.012 22.487-22.367 22.488-12.353 0-22.366-10.014-22.366-22.367v-1.807c-4.035-2.766-7.475-6.208-10.179-10.3-4.148-6.277-6.237-13.636-6.184-21.52l.106-17.112c.03-12.328 10.032-22.313 22.367-22.313 6.404 0 12.18 2.692 16.257 7.005a22.304 22.304 0 0116.257-7.005z" fill="#4393BB" fill-rule="nonzero"/><path d="M58.07 116.564a8.129 8.129 0 0016.256 0v-10.387a29.353 29.353 0 004.202-1.926c3.337-1.887 6.195-4.403 8.336-7.642 2.533-3.834 3.861-8.412 3.826-13.579l-.106-17.15a8.129 8.129 0 10-16.258 0V81.5c.004.537-.01 1.017-.047 1.455a8.129 8.129 0 11-16.162 0 16.127 16.127 0 01-.047-1.456V65.88a8.129 8.129 0 10-16.258 0l-.106 17.151c-.035 5.167 1.293 9.745 3.826 13.579 2.14 3.24 4.999 5.755 8.336 7.642 1.32.746 2.757 1.39 4.202 1.926v10.387z" fill="#FFF"/></g><g><path d="M117.946 158.852h16.043c11.034 0 19.979 8.945 19.979 19.979 0 11.034-8.945 19.978-19.979 19.978h-16.043c-11.034 0-19.978-8.944-19.978-19.978s8.944-19.979 19.978-19.979zm0 12.815a7.164 7.164 0 100 14.328h16.043a7.164 7.164 0 000-14.328h-16.043z" fill="#026090"/><path d="M117.52 160.501c-10.123 0-18.329 8.207-18.329 18.33 0 10.123 8.206 18.33 18.33 18.33h16.894c10.123 0 18.33-8.207 18.33-18.33 0-10.123-8.207-18.33-18.33-18.33H117.52zm0-2.71h16.895c11.62 0 21.04 9.42 21.04 21.04s-9.42 21.039-21.04 21.039H117.52c-11.62 0-21.039-9.42-21.039-21.04 0-11.619 9.42-21.038 21.04-21.038zm0 16.205a4.835 4.835 0 000 9.67h16.895a4.835 4.835 0 100-9.67H117.52zm0-2.71h16.895a7.544 7.544 0 010 15.089H117.52a7.544 7.544 0 010-15.089z" fill="#FFF" fill-rule="nonzero"/><path d="M180.123 159.292h15.69c10.791 0 19.539 8.748 19.539 19.539 0 10.79-8.748 19.539-19.539 19.539h-15.69c-10.791 0-19.54-8.748-19.54-19.54 0-10.79 8.749-19.538 19.54-19.538zm0 12.532a7.006 7.006 0 100 14.013h15.69a7.006 7.006 0 100-14.013h-15.69z" fill="#026090"/><path d="M179.52 160.501c-10.123 0-18.329 8.207-18.329 18.33 0 10.123 8.206 18.33 18.33 18.33h16.894c10.123 0 18.33-8.207 18.33-18.33 0-10.123-8.207-18.33-18.33-18.33H179.52zm0-2.71h16.895c11.62 0 21.04 9.42 21.04 21.04s-9.42 21.039-21.04 21.039H179.52c-11.62 0-21.039-9.42-21.039-21.04 0-11.619 9.42-21.038 21.04-21.038zm0 16.205a4.835 4.835 0 000 9.67h16.895a4.835 4.835 0 100-9.67H179.52zm0-2.71h16.895a7.544 7.544 0 010 15.089H179.52a7.544 7.544 0 010-15.089z" fill="#FFF" fill-rule="nonzero"/><path d="M241.946 158.852h16.043c11.034 0 19.979 8.945 19.979 19.979 0 11.034-8.945 19.978-19.979 19.978h-16.043c-11.034 0-19.978-8.944-19.978-19.978s8.944-19.979 19.978-19.979zm0 12.815a7.164 7.164 0 100 14.328h16.043a7.164 7.164 0 000-14.328h-16.043z" fill="#026090"/><path d="M241.52 160.501c-10.123 0-18.329 8.207-18.329 18.33 0 10.123 8.206 18.33 18.33 18.33h16.894c10.123 0 18.33-8.207 18.33-18.33 0-10.123-8.207-18.33-18.33-18.33H241.52zm0-2.71h16.895c11.62 0 21.04 9.42 21.04 21.04s-9.42 21.039-21.04 21.039H241.52c-11.62 0-21.039-9.42-21.039-21.04 0-11.619 9.42-21.038 21.04-21.038zm0 16.205a4.835 4.835 0 000 9.67h16.895a4.835 4.835 0 100-9.67H241.52zm0-2.71h16.895a7.544 7.544 0 010 15.089H241.52a7.544 7.544 0 010-15.089z" fill="#FFF" fill-rule="nonzero"/><path d="M305.09 159.21h15.756c10.837 0 19.622 8.784 19.622 19.62 0 10.837-8.785 19.622-19.622 19.622H305.09c-10.836 0-19.621-8.785-19.621-19.621 0-10.837 8.785-19.622 19.621-19.622zm0 12.585a7.036 7.036 0 100 14.072h15.756a7.036 7.036 0 000-14.072H305.09z" fill="#026090"/><path d="M304.52 160.501c-10.123 0-18.329 8.207-18.329 18.33 0 10.123 8.206 18.33 18.33 18.33h16.894c10.123 0 18.33-8.207 18.33-18.33 0-10.123-8.207-18.33-18.33-18.33H304.52zm0-2.71h16.895c11.62 0 21.04 9.42 21.04 21.04s-9.42 21.039-21.04 21.039H304.52c-11.62 0-21.039-9.42-21.039-21.04 0-11.619 9.42-21.038 21.04-21.038zm0 16.205a4.835 4.835 0 000 9.67h16.895a4.835 4.835 0 100-9.67H304.52zm0-2.71h16.895a7.544 7.544 0 010 15.089H304.52a7.544 7.544 0 010-15.089z" fill="#FFF" fill-rule="nonzero"/><path d="M137.975 185.02h38.465a6.19 6.19 0 000-12.379h-38.465a6.19 6.19 0 000 12.38z" stroke="#FFF" stroke-width="2.71"/><path d="M137.975 183.665h38.465a4.835 4.835 0 100-9.669h-38.465a4.835 4.835 0 000 9.67z" fill="#026090"/><path d="M199.976 186.375a7.544 7.544 0 010-15.088h38.465a7.544 7.544 0 110 15.088h-38.465z" fill="#FFF" fill-rule="nonzero"/><path d="M199.976 183.665h38.465a4.835 4.835 0 100-9.669h-38.465a4.835 4.835 0 000 9.67z" fill="#026090"/><path d="M199.976 183.665h38.465a4.835 4.835 0 100-9.669h-38.465a4.835 4.835 0 000 9.67z"/><path d="M261.977 186.375a7.544 7.544 0 110-15.088h38.465a7.544 7.544 0 010 15.088h-38.465z" fill="#FFF" fill-rule="nonzero"/><path d="M261.977 183.665h38.465a4.835 4.835 0 000-9.669h-38.465a4.835 4.835 0 000 9.67z"/><path d="M261.977 183.665h38.465a4.835 4.835 0 000-9.669h-38.465a4.835 4.835 0 000 9.67z" fill="#026090"/><g><path d="M469.73 166.686h9.736c6.696 0 12.124 5.437 12.124 12.145 0 6.707-5.428 12.144-12.124 12.144h-9.737c-6.696 0-12.124-5.437-12.124-12.144 0-6.708 5.428-12.145 12.124-12.145zm0 7.79a4.351 4.351 0 00-4.348 4.355 4.351 4.351 0 004.347 4.355h9.737a4.351 4.351 0 004.347-4.355 4.351 4.351 0 00-4.347-4.355h-9.737z" fill="#026090"/><path d="M469.529 167.815c-6.074 0-10.998 4.932-10.998 11.016s4.924 11.016 10.998 11.016h10.137c6.074 0 10.998-4.932 10.998-11.016s-4.924-11.016-10.998-11.016h-10.137zm0-1.629h10.137c6.972 0 12.623 5.661 12.623 12.645 0 6.983-5.651 12.644-12.623 12.644h-10.137c-6.972 0-12.623-5.66-12.623-12.644s5.651-12.645 12.623-12.645zm0 9.74c-1.602 0-2.9 1.3-2.9 2.905a2.903 2.903 0 002.9 2.905h10.137c1.602 0 2.9-1.3 2.9-2.905a2.903 2.903 0 00-2.9-2.906h-10.137zm0-1.63h10.137a4.53 4.53 0 014.527 4.535 4.53 4.53 0 01-4.527 4.534h-10.137a4.53 4.53 0 01-4.527-4.534 4.53 4.53 0 014.527-4.534z" fill="#FFF" fill-rule="nonzero"/><path d="M432.574 167.038h9.454c6.502 0 11.773 5.28 11.773 11.793 0 6.513-5.27 11.793-11.773 11.793h-9.454c-6.502 0-11.773-5.28-11.773-11.793 0-6.513 5.271-11.793 11.773-11.793zm0 7.564a4.225 4.225 0 00-4.221 4.229 4.225 4.225 0 004.221 4.228h9.454a4.225 4.225 0 004.222-4.228 4.225 4.225 0 00-4.222-4.229h-9.454z" fill="#026090"/><path d="M432.233 167.815c-6.074 0-10.998 4.932-10.998 11.016s4.924 11.016 10.998 11.016h10.137c6.074 0 10.997-4.932 10.997-11.016s-4.923-11.016-10.997-11.016h-10.137zm0-1.629h10.137c6.971 0 12.623 5.661 12.623 12.645 0 6.983-5.652 12.644-12.623 12.644h-10.137c-6.972 0-12.624-5.66-12.624-12.644s5.652-12.645 12.624-12.645zm0 9.74c-1.602 0-2.901 1.3-2.901 2.905a2.903 2.903 0 002.9 2.905h10.138c1.602 0 2.9-1.3 2.9-2.905a2.903 2.903 0 00-2.9-2.906h-10.137zm0-1.63h10.137a4.53 4.53 0 014.526 4.535 4.53 4.53 0 01-4.526 4.534h-10.137a4.53 4.53 0 01-4.527-4.534 4.53 4.53 0 014.527-4.534z" fill="#FFF" fill-rule="nonzero"/><path d="M444.505 183.365a4.53 4.53 0 01-4.526-4.534 4.53 4.53 0 014.526-4.534h23.08a4.53 4.53 0 014.526 4.534 4.53 4.53 0 01-4.526 4.534h-23.08z" fill="#FFF" fill-rule="nonzero"/><g transform="translate(419.61 166.186)"><use fill="#026090" xlink:href="#a"/><path stroke="#FFF" stroke-width="1.626" d="M24.896 16.363h23.08a3.716 3.716 0 003.713-3.718 3.716 3.716 0 00-3.714-3.719H24.896a3.716 3.716 0 00-3.714 3.719 3.716 3.716 0 003.714 3.718z"/></g></g><g fill-rule="nonzero"><path d="M381.463 171.818v-12.38c0-2.923 3.486-4.442 5.627-2.45l24.44 22.74a3.347 3.347 0 010 4.9l-24.44 22.74c-2.14 1.991-5.627.473-5.627-2.451v-12.38h-29.167a3.347 3.347 0 01-3.348-3.346v-14.026a3.347 3.347 0 013.348-3.347h29.167z"/><g stroke-linecap="square" stroke-linejoin="round" transform="translate(348.948 156.039)"><use fill="#4393BB" fill-rule="evenodd" xlink:href="#b"/><path stroke="#FFF" stroke-width="1.806" d="M34.611 14.823H2.097v15.832H34.61v16.897l1.519-1.413L60.57 23.4l.71-.661-.71-.661L36.13-.662 34.61-2.073v16.897z"/></g></g></g></g></svg>
```
--------------------------------------------------------------------------------
/convertigo/content.md:
--------------------------------------------------------------------------------
```markdown
# What is Convertigo Low Code Platform ?
Convertigo is an open source fullstack Low Code & No Code platform. The platform is used to build Enterprise Web & Mobile apps in a few days. Convertigo platform is composed of several components:
1. **Convertigo Server**: The back-end server part. Handles back-end connectors, micro-services execution, offline data device synchronization and serves Web & Mobile Web apps. Runs as a Docker container with the `convertigo` image
2. **Convertigo Studio**: Runs on a Windows or a MacOS workstation, Eclipse based IDE, used to program Back-end micro-services workflows and use the "Mobile Builder" edition to build Mobile & Web apps UIs in a MXDP (Multi eXperience Development Platform) Low code mode. Can be directly downloaded from [Convertigo](https://www.convertigo.com/get-started-page)
3. **Convertigo NoCode Studio**: The No Code App Builder to build form based apps as PWAs or Web applications with a Web Based NoCode studio intented for non technical developpers (Citizen Developpers)
Convertigo Community edition brought to you by Convertigo SA (Paris & San Francisco). The platform is currently used by more than 100K developers worldwide, building enterprise class mobile apps.
> [www.convertigo.com](https://www.convertigo.com)
%%LOGO%%
# How to use this image
## Quick start
```console
$ docker run --name C8O -d -p 28080:28080 %%IMAGE%%
```
This will start a container running the minimum Convertigo server. Convertigo uses images' **/workspace** directory to store configuration file and deployed projects as an Docker volume.
You can access the Server admin console on `http://[dockerhost]:28080/convertigo` and login using the default credentials: `admin / admin`.
The Server can also be accessed by HTTPS on `https://[dockerhost]:28443/convertigo` if SSL is configured (see the **HTTPS** section below).
## Link Convertigo to a CouchDB database for FullSync (Convertigo EE only)
Convertigo FullSync module uses Apache CouchDB 3.2.2 as NoSQL repository. You can use the **[couchdb](https://hub.docker.com/_/couchdb/)** docker image and link to it convertigo this way
Launch CouchDB container and name it 'fullsync'
```console
$ docker run -d --name fullsync couchdb:3.2.2
```
Then launch Convertigo and link it to the running 'fullsync' container. Convertigo Low Code sever will automatically use it as its fullsync repository.
```console
$ docker run -d --name C8O --link fullsync:couchdb -p 28080:28080 %%IMAGE%%
```
## Use embedded PouchDB as FullSync engine (not for production)
Convertigo FullSync is designed to use CouchDB server or cluster. Convertigo FullSync is also compatible with PouchDB but only for little projects or tests. Internet access is required to enable this feature.
It can be enabled directly at startup:
```console
$ docker run -d --name C8O -e JAVA_OPTS="-Dconvertigo.engine.fullsync.pouchdb=true" -p 28080:28080 %%IMAGE%%
```
## Link Convertigo Low Code Server to a Billing & Analytics database
### MySQL
MySQL is the recommended database for holding Convertigo Low Code server analytics. You can use this command to run convertigo and link it to a running MySQL container. Change `[mysql-container]` to the container name, and `[username for the c8oAnalytics db]`, `[password for specified db user]` with the values for your MySQL configuration.
```console
$ docker run -d --name C8O --link [mysql-container]:mysql -p 28080:28080 \
-e JAVA_OPTS="-Dconvertigo.engine.billing.enabled=true \
-Dconvertigo.engine.billing.persistence.jdbc.username=[username for the c8oAnalytics db] \
-Dconvertigo.engine.billing.persistence.jdbc.password=[password for specified db user] \
-Dconvertigo.engine.billing.persistence.jdbc.url=jdbc:mysql://mysql:3306/c8oAnalytics" \
%%IMAGE%%
```
## Where is Convertigo Low Code server storing deployed projects
Projects are deployed in the Convertigo workspace, a simple file system directory. You can map the docker container **/workspace** to your physical system by using:
```console
$ docker run --name C8O -v $(pwd):/workspace -d -p 28080:28080 %%IMAGE%%
```
You can share the same workspace by all Convertigo containers. In this case, when you deploy a project on a Convertigo container, it will be seen by others. This is the best way to build multi-instance load balanced Convertigo server farms.
**Be sure to have a really fast file sharing between instances !!! We have experienced that Azure File Share is not fast enough**
To avoid log and cache mixing, you have to add 2 variables for instance specific paths:
```console
-Dconvertigo.engine.cache_manager.filecache.directory=/workspace/cache/[instance name]
-Dconvertigo.engine.log4j.appender.CemsAppender.File=/workspace/logs/[instance name]/engine.log
```
## Make image with pre-deployed projects
If you want to make a vertical image ready to start with your application inside, you have to have your built projects **.car** files next to your `Dockerfile`:
```console
FROM %%IMAGE%%
COPY myProject.car /usr/local/tomcat/webapps/convertigo/WEB-INF/default_user_workspace/projects/
COPY myDependency.car /usr/local/tomcat/webapps/convertigo/WEB-INF/default_user_workspace/projects/
```
## Migrate from an earlier version of Convertigo Low Code Platform
- Stop the container to perform a backup. And just back the workspace directory. This will backup all the projects definitions and some project data.
- Start a new Convertigo docker container mapping the workspace
- All the workspace (Projects) will be automatically migrated to the new Convertigo MBaaS version
## Security
The default administration account of a Convertigo server is **admin** / **admin** and the **testplatform** is anonymous.
These accounts can be configured through the **administration console** and saved in the **workspace**.
### `CONVERTIGO_ADMIN_USER` and `CONVERTIGO_ADMIN_PASSWORD` Environment variables
You can change the default administration account :
```console
$ docker run -d --name C8O -e CONVERTIGO_ADMIN_USER=administrator -e CONVERTIGO_ADMIN_PASSWORD=s3cret -p 28080:28080 %%IMAGE%%
```
### `CONVERTIGO_TESTPLATFORM_USER` and `CONVERTIGO_TESTPLATFORM_PASSWORD` Environment variables
You can lock the **testplatform** by setting the account :
```console
$ docker run -d --name C8O -e CONVERTIGO_TESTPLATFORM_USER=tp_user -e CONVERTIGO_TESTPLATFORM_PASSWORD=s3cret -p 28080:28080 %%IMAGE%%
```
## HTTPS / SSL Configuration
In many cases, the Convertigo instance is behind a reverse proxy that handles HTTPS / SSL configuration. But you can configure the container to manage existing SSL certificates or dynamically generate one.
If the SSL configuration is correct, the Convertigo Server will listen **HTTP** on port `28080` and **HTTPS** on port `28443`.
### Provide existing certificate using the /ssl mount point
If you have an existing certificate and a private key, you can put them in **PEM** format in a folder (or in a Kubernetes secret):
- `key.pem` : the private key in PEM format (no password)
- `cert.pem` : the server certificate in PEM format, can also contain the full chain of certificates
- `chain.pem` : the optional chain of certificates not included in `cert.pem` using the PEM format
```console
$ docker run -d --name C8O -v <my SSL folder>:/ssl -p 28443:28443 %%IMAGE%%
```
If you want to expose both **HTTP** and **HTTPS** you can expose both **ports**:
```console
$ docker run -d --name C8O -v <my SSL folder>:/ssl -p 28080:28080 -p 28443:28443 %%IMAGE%%
```
### Provide existing certificate using environment variables
If you cannot mount a volume, you can probably add environment variables of previously described files. Content cannot be set directly in a variable but their base64 version can. Here are the variables to configure:
- `SSL_KEY_B64` : the private key in base64 PEM format (no password)
- `SSL_CERT_B64` : the server certificate in base64 PEM format, can also contain the full chain of certificates
- `SSL_CHAIN_B64` : the optional chain of certificates not included in `cert.pem` using the base64 PEM format
```console
$ SSL_KEY_B64=$(base64 key.pem)
$ SSL_CERT_B64=$(base64 cert.pem)
$ SSL_CHAIN_B64=$(base64 chain.pem)
$ docker run -d --name C8O -e SSL_KEY_B64="$SSL_KEY_B64" -e SSL_CERT_B64="$SSL_CERT_B64" -e SSL_CHAIN_B64="$SSL_CHAIN_B64" -p 28443:28443 %%IMAGE%%
```
### Generate and use a self-signed certificate
If you don't have certificate file, you can dynamically generate one for the first start. This will be an untrusted certificate for Browsers and HTTPS clients. This shouldn't be used for production environment.
Use the `SSL_SELFSIGNED` environment variable to indicate for what domain you want generate certificate.
```console
$ docker run -d --name C8O -e SSL_SELFSIGNED=mycomputer -p 28443:28443 %%IMAGE%%
```
Generated files can be retrieved if the `/ssl` mount point is configured on folder without `cert.pem` nor `key.pem`.
```console
$ docker run -d --name C8O -v <my empty SSL folder>:/ssl -e SSL_SELFSIGNED=mycomputer -p 28443:28443 %%IMAGE%%
```
## `JAVA_OPTS` Environment variable
Convertigo is based on a **Java** process with some defaults **JVM** options. You can override our defaults **JVM** options with you own.
Add any **Java JVM** options such as -D[something] :
```console
$ docker run -d --name C8O -e JAVA_OPTS="-DjvmRoute=server1" -p 28080:28080 %%IMAGE%%
```
[Here the list of convertigo specific properties](https://www.convertigo.com/documentation/latest/operating-guide/appendixes/#list-of-convertigo-java-system-properties) (don't forget the `-Dconvertigo.engine.` prefix).
## `LOG_STDOUT` and `LOG_FILE` Environment variables
Convertigo generates many logs in a **engine.log** file that can be consulted via the Convertigo Administration Console. In some environments, it's easiest to read logs from the container's standard output. Set this property `true` to enable console output. The default value is `false`.
Log file still exists until you add the `LOG_FILE=false` environment variable :
```console
docker run -d --name C8O -e LOG_STDOUT=true -e LOG_FILE=false -p 28080:28080 convertigo
```
## `JXMX` Environment variable
Convertigo tries to allocate this amount of memory in the container and will automatically reduce it until the value is compatible for the Docker memory constraints. Once the best value found, it is used as `-Xmx=${JXMX}m` parameter for the JVM.
The default `JXMX` value is `2048` and can be defined :
```console
$ docker run -d --name C8O -e JXMX="4096" -p 28080:28080 %%IMAGE%%
```
## `COOKIE_PATH` Environment variable
Convertigo generates a `JSESSIONID` to maintain the user session and stores in a **cookie**. The **cookie** is set for the server path `/` by default. In case of a front server with multiple services for different paths, you can set a path restriction for the **cookie** with the `JSESSIONID`. Just define the `COOKIE_PATH` environment variable with a compatible path.
The default `COOKIE_PATH` value is `/` and can be defined :
```console
$ docker run -d --name C8O -e COOKIE_PATH="/convertigo" -p 28080:28080 %%IMAGE%%
```
## `COOKIE_SECURE` Environment variable
Convertigo uses a **cookie** to maintain sessions. Requests on port `28080` are **HTTP** but we advise to use an **HTTPS** front for production (nginx, kubernetes ingress, ...). In this case, you can secure your cookies to be used only with secured connections by adding the `Secure` flag.
The Secure flag can be enabled by setting the `COOKIE_SECURE` environment variable to `true`. Once enabled, cookies and sessions aren't working through an **HTTP** connection.
The default `COOKIE_SECURE` value is `false` and can be defined :
```console
$ docker run -d --name C8O -e COOKIE_SECURE="true" -p 28080:28080 %%IMAGE%%
```
**Note :** if you have set the **SSL** configuration and you access the **HTTPS 28443** port, cookies are automatically `Secure`.
## `COOKIE_SAMESITE` Environment variable
Allow to configure the **SameSite** parameter for generated cookies. Can be empty, `none`, `lax` or `strict`.
The default `COOKIE_SAMESITE` value is **empty** and can be defined this way:
```console
$ docker run -d --name C8O -e COOKIE_SAMESITE=lax -p 28080:28080 %%IMAGE%%
```
## `SESSION_TIMEOUT` Environment variable
Allow to configure the default Tomcat **session-timeout** in minutes. This value is used for non-project calls (Administration console, Fullsync...). This value is overridden by each projects' calls (Sequence, Transaction ...).
The default `SESSION_TIMEOUT` value is **30** and can be defined this way:
```console
$ docker run -d --name C8O -e SESSION_TIMEOUT=5 -p 28080:28080 %%IMAGE%%
```
## `DISABLE_SUDO` Environment variable
The image includes **sudo** command line, configured to allow the **convertigo** user to use it without password and to perform some **root** action inside the container. This variable allows to disable this permission.
The default `DISABLE_SUDO` value is **empty** and can be defined this way:
```console
$ docker run -d --name C8O -e DISABLE_SUDO=true -p 28080:28080 %%IMAGE%%
```
## `ENABLE_JDWP_DEBUG` Environment variable
Convertigo operates using the JVM (Java Virtual Machine). To enable remote debugging of the JVM, it's necessary to start it with specific options. By default, this configuration is not enabled. However, if you wish to automatically activate remote debugging over the JDWP port 8000, set the `ENABLE_JDWP_DEBUG` value to **true**.
The default `ENABLE_JDWP_DEBUG` value is **false** and can be defined this way:
```console
$ docker run -d –name C8O -e ENABLE_JDWP_DEBUG=true -p 28080:28080 %%IMAGE%%
```
## Pre-configurated Docker Compose file
You can use [this Docker Compose file](https://github.com/convertigo/docker/blob/master/compose/mbaas/docker-compose.yml) to run a complete Convertigo Low Code server with FullSync repository and MySQL analytics in a few command lines.
```console
$ mkdir c8oMBaaS
$ cd c8oMBaaS
$ wget https://raw.githubusercontent.com/convertigo/docker/master/compose/mbaas/docker-compose.yml
$ docker compose up -d
```
```
--------------------------------------------------------------------------------
/mariadb/content.md:
--------------------------------------------------------------------------------
```markdown
# What is MariaDB?
MariaDB Server is one of the most popular database servers in the world. It's made by the original developers of MySQL and guaranteed to stay open source. Notable users include Wikipedia, DBS Bank, and ServiceNow.
The intent is also to maintain high compatibility with MySQL, ensuring a library binary equivalency and exact matching with MySQL APIs and commands. MariaDB developers continue to develop new features and improve performance to better serve its users.
%%LOGO%%
# How to use this image
The %%IMAGE%% has a number of tags, and of note is `latest`, as the latest stable version, and `lts`, as the last long term support release.
## Running the container
### Configuration
#### Port binding
By default, the database running within the container will listen on port 3306. You can expose the container port 3306 to the host port 3306 with the `-p 3306:3306` argument to `docker run`, like the command below:
```console
$ docker run --name some-%%REPO%% -p 3306:3306 %%IMAGE%%:latest
```
### Starting using a minimal configuration
The environment variables required to use this image involves the setting of the root user password:
```console
$ docker run --detach --name some-%%REPO%% --env MARIADB_ROOT_PASSWORD=my-secret-pw %%IMAGE%%:latest
```
or:
```console
$ docker run --detach --name some-%%REPO%% --env MARIADB_ALLOW_EMPTY_ROOT_PASSWORD=1 %%IMAGE%%:latest
```
or:
```console
$ docker run --detach --name some-%%REPO%% --env MARIADB_RANDOM_ROOT_PASSWORD=1 %%IMAGE%%:latest
```
... where the container logs will contain the generated root password.
## %%COMPOSE%%
Run `docker compose up`, wait for it to initialize completely, and visit `http://localhost:8080` or `http://host-ip:8080` (as appropriate).
### Start a `%%IMAGE%%` server instance with user, password and database
Starting a MariaDB instance with a user, password, and a database:
```console
$ docker run --detach --name some-%%REPO%% --env MARIADB_USER=example-user --env MARIADB_PASSWORD=my_cool_secret --env MARIADB_DATABASE=exmple-database --env MARIADB_ROOT_PASSWORD=my-secret-pw %%IMAGE%%:latest
```
### Start a `%%IMAGE%%` server instance in a network
As applications talk to MariaDB, MariaDB needs to start in the same network as the application:
```console
$ docker network create some-network
$ docker run --detach --network some-network --name some-%%REPO%% --env MARIADB_USER=example-user --env MARIADB_PASSWORD=my_cool_secret --env MARIADB_ROOT_PASSWORD=my-secret-pw %%IMAGE%%:latest
$ docker run --detach --network some-network --name some-application --env APP_DB_HOST=some-%%REPO%% --env APP_DB_USER=example-user --env APP_DB_PASSWD=my_cool_secret some-application
```
... where `some-network` is a newly created network (other than `bridge` as the default network), `some-%%REPO%%` is the name you want to assign to your container, `my-secret-pw` is the password to be set for the MariaDB root user. See the list above for relevant tags to match your needs and environment. `some-application` and then environment variable `APP_DB_HOST`, `APP_DB_USER` and `APP_DB_PASSWD` are the application's configuration for its database connection.
## Connect to MariaDB from the MariaDB command line client
The following command starts another `%%IMAGE%%` container instance and runs the `mariadb` command line client against your original `%%IMAGE%%` container, allowing you to execute SQL statements against your database instance:
```console
$ docker run -it --network some-network --rm %%IMAGE%% mariadb -h some-%%REPO%% -u example-user
```
... where `some-%%REPO%%` is the name of your original `%%IMAGE%%` container (connected to the `some-network` Docker network).
This image can also be used as a client for non-Docker or remote instances:
```console
$ docker run -it --rm %%IMAGE%% mariadb --host <server container IP> --user example-user --password --database test
```
That will give you a standard MariaDB prompt. You can test it with:
```console
MariaDB [(none)]> \s
--------------
client/mariadb Ver 15.1 Distrib 10.6.16-MariaDB, for Linux (x86_64) using EditLine wrapper
Connection id: 20
Current database: test
Current user: example-user@bark
SSL: Not in use
Current pager: stdout
Using outfile: ''
Using delimiter: ;
Server: MariaDB
Server version: 10.6.16-MariaDB Source distribution
Protocol version: 10
Connection: 192.168.178.73 via TCP/IP
Server characterset: latin1
Db characterset: latin1
Client characterset: utf8mb3
Conn. characterset: utf8mb3
TCP port: 3306
Uptime: 6 min 4 sec
Threads: 1 Questions: 32 Slow queries: 0 Opens: 20 Open tables: 13 Queries per second avg: 0.087
--------------
```
... which will give you the version and connection information. You can then use `exit` to leave the MariaDB command line client and the client container.
More information about the MariaDB command-line client can be found in the [MariaDB Knowledge Base : MariaDB Command Line Client](https://mariadb.com/kb/en/mariadb-command-line-client/).
## Container shell access
The `docker exec` command allows you to run commands inside the running container. The following command line will give you a bash shell inside your `%%IMAGE%%` container:
```console
$ docker exec -it some-%%REPO%% bash
```
## MariaDB-Backup
As MariaDB-Backup is highly coupled with the server version, it can be useful to use the `mariadb-backup` in the %%REPO%% container of an explicit version:
```console
$ docker run --volume /backup-volume:/backup --rm %%REPO%%:10.6.15 mariadb-backup --help
```
## Container viewing MariaDB logs
The log is available through Docker's container log:
```console
$ docker logs some-%%REPO%%
```
## Using a custom MariaDB configuration file
Custom configuration files should end in `.cnf` and be mounted read only at the directory `/etc/mysql/conf.d`. These files should contain the minimal changes from the MariaDB workload required for your application/environment. A MariaDB configuration file will have a `[mariadb]` group followed by `variable` = `value` settings per [Setting Server System Variables](https://mariadb.com/kb/en/server-system-variables/#setting-server-system-variables) or [option-prefix-variable](https://mariadb.com/kb/en/configuring-mariadb-with-option-files/#option-prefixes).
The `%%IMAGE%%` image configuration contains the Ubuntu MariaDB variables with two custom changes for the container:
[host-cache-size=0](https://mariadb.com/kb/en/server-system-variables/#host_cache_size)
[skip-name-resolve](https://mariadb.com/kb/en/server-system-variables/#skip_name_resolve)
These disable the authentication of `user@hostname` users. To re-enable the `skip-name-resolve` use `disable-skip-name-resolve` as variable or argument. When enabled, the `host-cache-size` should be sufficient for the number of containers connecting to the `%%IMAGE%%`.
To view the resulting configuration of your `%%IMAGE%%` container:
```console
$ docker run --name some-%%REPO%% -v /my/custom:/etc/mysql/conf.d --rm %%IMAGE%%:latest my_print_defaults --mysqld
```
### Configuration without a `cnf` file
Many configuration options can be passed as flags to `mariadbd`. This will give you the flexibility to customize the container without needing a `cnf` file. For example, if you want to run on port 3808 just run the following:
```console
$ docker run --name some-%%REPO%% -e MARIADB_ROOT_PASSWORD=my-secret-pw -d %%IMAGE%%:latest --port 3808
```
If you would like to see a complete list of available options, just run:
```console
$ docker run -it --rm %%IMAGE%%:latest --verbose --help
```
## Environment Variables
When you start the `%%IMAGE%%` image, you can adjust the initialization of the MariaDB instance by passing one or more environment variables on the `docker run` command line. Do note that all of the variables, except `MARIADB_AUTO_UPGRADE`, will have no effect if you start the container with a data directory that already contains a database. I.e. any pre-existing database will always be left untouched on container startup.
One of `MARIADB_RANDOM_ROOT_PASSWORD`, `MARIADB_ROOT_PASSWORD_HASH`, `MARIADB_ROOT_PASSWORD` or `MARIADB_ALLOW_EMPTY_ROOT_PASSWORD` (or equivalents, including `*_FILE`), is required. The other environment variables are optional.
There is a large list of environment variables and the complete list is documented on [MariaDB's Knowledge Base : MariaDB Server Docker Official Image Environment Variables](https://mariadb.com/kb/en/mariadb-server-docker-official-image-environment-variables/).
### `MARIADB_AUTO_UPGRADE`
When this environment variable is set, this will run the [mariadb-upgrade](https://mariadb.com/kb/en/mariadb-upgrade/), if needed, so any changes in the MariaDB system tables required to expose new features will be made. This may impeed some [downgrade options](https://mariadb.com/kb/en/downgrading-between-major-versions-of-mariadb/). Unless the environment variable `MARIADB_DISABLE_UPGRADE_BACKUP` is set, there will be a backup of the system tables created as `system_mysql_backup_*.sql.zst` in the top level of the data directory to assist in the downgrade if needed.
## Secrets
As an alternative to passing sensitive information via environment variables, `_FILE` may be appended to the previously listed environment variables, causing the initialization script to load the values for those variables from files present in the container. In particular, this can be used to load passwords from Docker secrets stored in `/run/secrets/<secret_name>` files. For example:
```console
$ docker run --name some-mysql -e MARIADB_ROOT_PASSWORD_FILE=/run/secrets/mariadb-root -d %%IMAGE%%:latest
```
# Initializing the database contents
When a container is started for the first time, a new database with the specified name will be created and initialized with the provided configuration variables. Furthermore, it will execute files with extensions `.sh`, `.sql`, `.sql.gz`, `.sql.xz` and `.sql.zst` that are found in `/docker-entrypoint-initdb.d`. Files will be executed in alphabetical order. `.sh` files without file execute permission are sourced rather than executed. You can easily populate your `%%IMAGE%%` services by [mounting a SQL dump into that directory](https://docs.docker.com/storage/bind-mounts/) and provide [custom images](https://docs.docker.com/reference/dockerfile/) with contributed data. SQL files will be imported by default to the database specified by the `MARIADB_DATABASE` variable.
# Caveats
## Where to Store Data
Important note: There are several ways to store data used by applications that run in Docker containers. We encourage users of the `%%IMAGE%%` images to familiarize themselves with the options available, including:
- Use a named volume using the container manager to manage the storage of your database data [by writing the database files to disk on the host system using its own internal volume management](https://docs.docker.com/storage/volumes/). This is the default and is easy and fairly transparent to the user. The downside is that the files may be hard to locate for tools and applications that run directly on the host system, i.e. outside containers.
- Create a data directory on the host system (outside the container) and [mount this to a directory visible from inside the container](https://docs.docker.com/storage/bind-mounts/). This places the database files in a known location on the host system, and makes it easy for tools and applications on the host system to access the files. The downside is that the user needs to make sure that the directory exists, and that e.g. directory permissions and other security mechanisms on the host system are set up correctly.
The Docker documentation is a good starting point for understanding the different storage options and variations, and there are multiple blogs and forum postings that discuss and give advice in this area. We will simply show the basic procedure here for the latter option above:
1. Create a data directory on a suitable volume on your host system, e.g. `/my/own/datadir`.
2. Start your `%%IMAGE%%` container like this:
```console
$ docker run --name some-%%REPO%% -v /my/own/datadir:/var/lib/mysql:Z -e MARIADB_ROOT_PASSWORD=my-secret-pw -d %%IMAGE%%:latest
```
The `-v /my/own/datadir:/var/lib/mysql:Z` part of the command mounts the `/my/own/datadir` directory from the underlying host system as `/var/lib/mysql` inside the container, where MariaDB by default will write its data files.
## No connections until MariaDB init completes
If there is no database initialized when the container starts, then a default database will be created. While this is the expected behavior, this means that it will not accept incoming connections until such initialization completes. This may cause issues when using automation tools, such as `docker compose`, which start several containers simultaneously.
## Health/Liveness/Readiness Checking
See [the "Official Images" FAQ](https://github.com/docker-library/faq#healthcheck) for why there is no default `HEALTHCHECK` directive. However, you can use the `healthcheck.sh` script to choose from a (non-exhaustive) list of tests to check for whatever you consider health/liveness/readiness. Refer to the [MariaDB Knowledge Base : Using Healthcheck.sh](https://mariadb.com/kb/en/using-healthcheck-sh-script/) to learn about how to use it and which exact tests are provided.
## Usage against an existing database
If you start your `%%IMAGE%%` container instance with a data directory that already contains a database (specifically, a `mysql` subdirectory), no environment variables that control initialization will be needed or examined, and no pre-existing databases will be changed. The only exception is the non-default `MARIADB_AUTO_UPGRADE` environment variable, that might cause `mysql_upgrade`/`mariadb-upgrade` to run, which might change the system tables.
## Backups and Restores
Backing up and restoring databases is important in containers too. The documentation on how to do this can be found on the [MariaDB Knowledge Base : Container Backup and Restoration](https://mariadb.com/kb/en/backups-and-restoration/).
## Frequently Asked Questions / How to reset root and user passwords
This is documented on [MariaDB Knowledge Base : Frequenty Asked Questions of Docker Official Image](https://mariadb.com/kb/en/frequenty-asked-questions-of-docker-official-image/#how-to-reset-passwords).
## How to install MariaDB plugins
This is documented on [MariaDB Knowledge Base : Adding Plugins to the Docker Official Image](https://mariadb.com/kb/en/adding-plugins-to-the-mariadb-docker-official-image/).
# Related Images
- [MariaDB MaxScale](https://hub.docker.com/r/mariadb/maxscale/tags)
- [MariaDB ColumnStore](https://hub.docker.com/r/mariadb/columnstore/tags)
# Compose File Examples
Example compose files using this `%%IMAGE%%` are located in %%GITHUB-REPO%% in the `/examples` folder.
```
--------------------------------------------------------------------------------
/friendica/content.md:
--------------------------------------------------------------------------------
```markdown
# What is Friendica?
Friendica is a decentralised communications platform that integrates social communication. Our platform links to independent social projects and corporate services.
%%LOGO%%
# How to use this image
The images are designed to be used in a micro-service environment. There are two types of the image you can choose from.
The `apache` tag contains a full Friendica installation including an apache web server. It is designed to be easy to use and gets you running pretty fast. This is also the default for the `latest` tag and version tags that are not further specified.
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.
## Using the apache image
You need at least one other mariadb/mysql-container to link it to Friendica.
The apache image contains a webserver and exposes port 80. To start the container type:
```console
$ docker run -d -p 8080:80 --network some-network %%IMAGE%%
```
Now you can access the Friendica installation wizard at http://localhost:8080/ from your host system.
## Using the fpm image
To use the fpm image you need an additional web server that can proxy http-request to the fpm-port of the container. For fpm connection this container exposes port 9000. In most cases you might want use another container or your host as proxy. If you use your host you can address your Friendica container directly on port 9000. If you use another container, make sure that you add them to the same docker network (via `docker run --network <NAME> ...` or a `compose.yaml` file). In both cases you don't want to map the fpm port to you host.
```console
$ docker run -d %%IMAGE%%:fpm
```
As the fastCGI-Process is not capable of serving static files (style sheets, images, ...) the webserver needs access to these files. This can be achieved with the `volumes-from` option. You can find more information in the Docker Compose section.
## Background tasks
Friendica requires background tasks to fetch and send all kind of messages and maintain the complete instance. This setup is crucial for the Friendica node. There are two options to enable background tasks for Friendica:
- Using the default Image and manually setup background tasks (see Friendica [Install](https://github.com/friendica/friendica/blob/2021.03-rc/doc/Install.md#required-background-tasks))
- Using the default image (apache, fpm, fpm-alpine) and starting a dedicated `cron` instance and use `cron.sh` as startup command (like this [Example](https://github.com/friendica/docker/blob/stable/.examples/docker-compose/insecure/mariadb-cron-redis/apache/docker-compose.yml))
## Possible Environment Variables
**Friendica Settings**
- `FRIENDICA_URL` The Friendica complete URL including protocol, domain and subpath (example: https://friendica.local/sub/ ).
- `FRIENDICA_TZ` The default localization of the Friendica server.
- `FRIENDICA_LANG` The default language of the Friendica server.
- `FRIENDICA_SITENAME` The Sitename of the Friendica server.
- `FRIENDICA_NO_VALIDATION` If set to `true`, the URL and E-Mail validation will be disabled.
- `FRIENDICA_DATA` Set the name of the storage provider (e.g `Filesystem` to use filesystem), default ist the DB backend.
- `FRIENDICA_DATA_DIR` The data directory of the Friendica server (Default: /var/www/data).
- `FRIENDICA_UPGRADE` Force starting the Friendica update even it's the same version (Default: `false`).
**Friendica Logging**
- `FRIENDICA_DEBUGGING` If set to `true`, the logging of Friendica is enabled.
- `FRIENDICA_LOGFILE` (optional) The path to the logfile (Default: /var/www/friendica.log).
- `FRIENDICA_LOGLEVEL` (optional) The loglevel to log (Default: notice).
- `FRIENDICA_LOGGER` (optional) Set the type - stream, syslog, monolog (Default: stream).
- `FRIENDICA_SYSLOG_FLAGS` (optional) In case syslog is used, set the corresponding flags (Default: `LOG_PID | LOG_ODELAY | LOG_CONS | LOG_PERROR`).
- `FRIENDICA_SYSLOG_FACTORY` (optional) In case syslog is used, set the corresponding factory (Default: `LOG_USER`).
**Database** (**required at installation**)
- `MYSQL_USER` Username for the database user using mysql / mariadb.
- `MYSQL_PASSWORD` Password for the database user using mysql / mariadb.
- `MYSQL_DATABASE` Name of the database using mysql / mariadb.
- `MYSQL_HOST` Hostname of the database server using mysql / mariadb.
- `MYSQL_PORT` Port of the database server using mysql / mariadb (Default: `3306`)
**Lock Driver (Redis)**
- `REDIS_HOST` The hostname of the redis instance (in case of locking).
- `REDIS_PORT` (optional) The port of the redis instance (in case of locking).
- `REDIS_PW` (optional) The password for the redis instance (in case of locking).
- `REDIS_DB` (optional) The database instance of the redis instance (in case of locking).
**PHP limits**
- `PHP_MEMORY_LIMIT` (default `512M`) This sets the maximum amount of memory in bytes that a script is allowed to allocate. This is meant to help prevent poorly written scripts from eating up all available memory, but it can prevent normal operation if set too tight.
- `PHP_UPLOAD_LIMIT` (default `512M`) This sets the upload limit (`post_max_size` and `upload_max_filesize`) for big files. Note that you may have to change other limits depending on your client, webserver or operating system.
## Administrator account
Because Friendica links the administrator account to a specific mail address, you **have** to set a valid address for `MAILNAME`.
## Mail settings
The binary `ssmtp` is used for the `mail()` support of Friendica.
You have to set the `--hostname/-h` parameter correctly to use the right domainname for the `mail()` command.
You have to set a valid SMTP-MTA for the `SMTP` environment variable to enable mail support in Friendica. A valid SMTP-MTA would be, for example, `mx.example.org`.
The following environment variables are possible for the SMTP examples.
- `SMTP` Address of the SMTP Mail-Gateway. (**required**)
- `SMTP_PORT` Port of the SMTP Mail-Gateway. (Default: 587)
- `SMTP_DOMAIN` The sender domain. (**required** - e.g. `friendica.local`)
- `SMTP_FROM` Sender user-part of the address. (Default: `no-reply` - e.g. [email protected])
- `SMTP_TLS` Use TLS for connecting the SMTP Mail-Gateway. (Default: empty)
- `SMTP_STARTTLS` Use STARTTLS for connecting the SMTP Mail-Gateway. (Default: `On`)
- `SMTP_AUTH` Auth mode for the SMTP Mail-Gateway. (Default: `On`)
- `SMTP_AUTH_USER` Username for the SMTP Mail-Gateway. (Default: empty)
- `SMTP_AUTH_PASS` Password for the SMTP Mail-Gateway. (Default: empty)
**Addition to STARTTLS**
the `tls_starttls` setting is either `On` or `Off`, but never unset. That's because in case it's unset, `starttls` would be activated by default (which would need additional configuration like a separate port).
## Database settings
You have to add the Friendica container to the same network as the running database container, e. g. `--network some-network`, and then use `mysql` as the database host on setup.
## Persistent data
The Friendica installation and all data beyond what lives in the database (file uploads, etc) is stored in the [unnamed docker volume](https://docs.docker.com/storage/volumes/) volume `/var/www/html`. The docker daemon will store that data within the docker directory `/var/lib/docker/volumes/...`. That means your data is saved even if the container crashes, is stopped or deleted. To make your data persistent to upgrading and get access for backups is using named docker volume or mount a host folder. To achieve this you need one volume for your database container and Friendica.
Friendica:
- `/var/www/html/` folder where all Friendica data lives
```console
$ docker run -d \
-v friendica-vol-1:/var/www/html \
--network some-network
%%IMAGE%%
```
Database:
- `/var/lib/mysql` MySQL / MariaDB Data
```console
$ docker run -d \
-v mysql-vol-1:/var/lib/mysql \
--network some-network
mariadb
```
## Automatic installation
The Friendica image supports auto configuration via environment variables. You can preconfigure everything that is asked on the install page on first run. To enable the automatic installation, you have to the following environment variables:
- `FRIENDICA_URL` The Friendica complete URL including protocol, domain and subpath (example: https://friendica.local/sub/ ).
- `FRIENDICA_ADMIN_MAIL` E-Mail address of the administrator.
- `MYSQL_USER` Username for the database user using mysql / mariadb.
- `MYSQL_PASSWORD` Password for the database user using mysql / mariadb.
- `MYSQL_DATABASE` Name of the database using mysql / mariadb.
- `MYSQL_HOST` Hostname of the database server using mysql / mariadb.
# Docker Secrets
As an alternative to passing sensitive information via environment variables, _FILE may be appended to the previously listed environment variables, causing the initialization script to load the values for those variables from files present in the container. In particular, this can be used to load passwords from Docker secrets stored in /run/secrets/<secret_name> files. For example:
```yaml
services:
db:
image: mariadb
restart: always
volumes:
- db:/var/lib/mysql
environment:
- MYSQL_DATABASE_FILE=/run/secrets/mysql_database
- MYSQL_USER_FILE=/run/secrets/mysql_user
- MYSQL_PASSWORD_FILE=/run/secrets/mysql_password
secrets:
- mysql_database
- mysql_password
- mysql_user
app:
image: friendica
restart: always
volumes:
- friendica:/var/www/html
ports:
- "8080:80"
environment:
- MYSQL_HOST=db
- MYSQL_DATABASE_FILE=/run/secrets/mysql_database
- MYSQL_USER_FILE=/run/secrets/mysql_user
- MYSQL_PASSWORD_FILE=/run/secrets/mysql_password
- FRIENDICA_ADMIN_MAIL_FILE=/run/secrets/friendica_admin_mail
depends_on:
- db
secrets:
- friendica_admin_mail
- mysql_database
- mysql_password
- mysql_user
volumes:
db:
friendica:
secrets:
friendica_admin_mail:
file: ./friendica_admin_mail.txt # put admin email to this file
mysql_database:
file: ./mysql_database.txt # put mysql database name to this file
mysql_password:
file: ./mysql_password.txt # put mysql password to this file
mysql_user:
file: ./mysql_user.txt # put mysql username to this file
```
Currently, this is only supported for `FRIENDICA_ADMIN_MAIL`, `MYSQL_DATABASE`, `MYSQL_PASSWORD`, `MYSQL_USER`.
# Maintenance of the image
## Updating to a newer version
You have to pull the latest image from the hub (`docker pull %%IMAGE%%`). The stable branch gets checked at every startup and will get updated if no installation was found or a new image is used.
# Running this image with Docker Compose
The easiest way to get a fully featured and functional setup is using a `compose.yaml` file. There are too many different possibilities to setup your system, so here are only some examples what you have to look for.
At first make sure you have chosen the right base image (fpm or apache) and added the features you wanted (see below). In every case you want to add a database container and docker volumes to get easy access to your persistent data. When you want your server reachable from the internet adding HTTPS-encryption is mandatory! See below for more information.
## Base version - apache
This version will use the apache image and add a mariaDB container. The volumes are set to keep your data persistent. This setup provides **no ssl encryption** and is intended to run behind a proxy.
Make sure to set the variable `MYSQL_PASSWORD` before run this setup.
```yaml
services:
db:
image: mariadb
restart: always
volumes:
- db:/var/lib/mysql
environment:
- MYSQL_USER=friendica
- MYSQL_PASSWORD=
- MYSQL_DATABASE=friendica
- MYSQL_RANDOM_ROOT_PASSWORD=yes
app:
image: %%IMAGE%%
restart: always
volumes:
- friendica:/var/www/html
ports:
- "8080:80"
environment:
- MYSQL_HOST=db
- MYSQL_USER=friendica
- MYSQL_PASSWORD=
- MYSQL_DATABASE=friendica
- [email protected]
depends_on:
- db
volumes:
db:
friendica:
```
Then run `docker compose up -d`, now you can access Friendica at http://localhost:8080/ from your system.
## Base version - FPM
When using the FPM image you need another container that acts as web server on port 80 and proxies requests to the Friendica container. In this example a simple nginx container is combined with the Friendica-fpm image and a MariaDB database container. The data is stored in docker volumes. The nginx container also need access to static files from your Friendica installation. It gets access to all the volumes mounted to Friendica via the `volumes_from` option. The configuration for nginx is stored in the configuration file `nginx.conf` that is mounted into the container.
An example can be found in the [examples section](https://github.com/friendica/docker/tree/master/.examples).
As this setup does **not include encryption** it should to be run behind a proxy.
Prerequisites for this example:
- Make sure to set the variable `MYSQL_PASSWORD` and `MYSQL_USER` before you run the setup.
- Create a `nginx.conf` in the same directory as the `compose.yaml` file (take it from [example](https://github.com/friendica/docker/tree/master/.examples/docker-compose/with-traefik-proxy/mariadb-cron-smtp/fpm/web/nginx.conf))
```yaml
services:
db:
image: mariadb
restart: always
volumes:
- db:/var/lib/mysql
environment:
- MYSQL_USER=friendica
- MYSQL_PASSWORD=
- MYSQL_DATABASE=friendica
- MYSQL_RANDOM_ROOT_PASSWORD=yes
app:
image: %%IMAGE%%:fpm
restart: always
volumes:
- friendica:/var/www/html
environment:
- MYSQL_HOST=db
- MYSQL_USER=friendica
- MYSQL_PASSWORD=
- MYSQL_DATABASE=friendica
- [email protected]
networks:
- proxy-tier
- default
web:
image: nginx
ports:
- 8080:80
links:
- app
volumes:
- ./nginx.conf:/etc/nginx/nginx.conf:ro
restart: always
networks:
- proxy-tier
volumes:
db:
friendica:
networks:
proxy-tier:
```
Then run `docker compose up -d`, now you can access Friendica at http://localhost:8080/ from your system.
# Special settings for DEV/RC images
The `*-dev` and `*-rc` branches are directly downloaded and verified at each docker start to ensure that the latest sources are used. The parameter `FRIENDICA_UPGRADE` is required to be `true` (Default: `false`) to activate this behavior.
# Questions / Issues
If you got any questions or problems using the image, please visit our [Github Repository](https://github.com/friendica/docker) and write an issue.
```
--------------------------------------------------------------------------------
/postgres/content.md:
--------------------------------------------------------------------------------
```markdown
# What is PostgreSQL?
PostgreSQL, often simply "Postgres", is an object-relational database management system (ORDBMS) with an emphasis on extensibility and standards-compliance. As a database server, its primary function is to store data, securely and supporting best practices, and retrieve it later, as requested by other software applications, be it those on the same computer or those running on another computer across a network (including the Internet). It can handle workloads ranging from small single-machine applications to large Internet-facing applications with many concurrent users. Recent versions also provide replication of the database itself for security and scalability.
PostgreSQL implements the majority of the SQL:2011 standard, is ACID-compliant and transactional (including most DDL statements) avoiding locking issues using multiversion concurrency control (MVCC), provides immunity to dirty reads and full serializability; handles complex SQL queries using many indexing methods that are not available in other databases; has updateable views and materialized views, triggers, foreign keys; supports functions and stored procedures, and other expandability, and has a large number of extensions written by third parties. In addition to the possibility of working with the major proprietary and open source databases, PostgreSQL supports migration from them, by its extensive standard SQL support and available migration tools. And if proprietary extensions had been used, by its extensibility that can emulate many through some built-in and third-party open source compatibility extensions, such as for Oracle.
> [wikipedia.org/wiki/PostgreSQL](https://en.wikipedia.org/wiki/PostgreSQL)
%%LOGO%%
# How to use this image
## start a postgres instance
```console
$ docker run --name some-postgres -e POSTGRES_PASSWORD=mysecretpassword -d %%IMAGE%%
```
The default `postgres` user and database are created in the entrypoint with `initdb`.
> The postgres database is a default database meant for use by users, utilities and third party applications.
>
> [postgresql.org/docs](https://www.postgresql.org/docs/14/app-initdb.html)
## ... or via `psql`
```console
$ docker run -it --rm --network some-network %%IMAGE%% psql -h some-postgres -U postgres
psql (14.3)
Type "help" for help.
postgres=# SELECT 1;
?column?
----------
1
(1 row)
```
## %%COMPOSE%%
Run `docker compose up`, wait for it to initialize completely, and visit `http://localhost:8080` or `http://host-ip:8080` (as appropriate).
# How to extend this image
There are many ways to extend the `%%REPO%%` image. Without trying to support every possible use case, here are just a few that we have found useful.
## Environment Variables
The PostgreSQL image uses several environment variables which are easy to miss. The only variable required is `POSTGRES_PASSWORD`, the rest are optional.
**Warning**: the Docker specific variables will only have an effect if you start the container with a data directory that is empty; any pre-existing database will be left untouched on container startup.
### `POSTGRES_PASSWORD`
This environment variable is required for you to use the PostgreSQL image. It must not be empty or undefined. This environment variable sets the superuser password for PostgreSQL. The default superuser is defined by the `POSTGRES_USER` environment variable.
**Note 1:** The PostgreSQL image sets up `trust` authentication locally so you may notice a password is not required when connecting from `localhost` (inside the same container). However, a password will be required if connecting from a different host/container.
**Note 2:** This variable defines the superuser password in the PostgreSQL instance, as set by the `initdb` script during initial container startup. It has no effect on the `PGPASSWORD` environment variable that may be used by the `psql` client at runtime, as described at [https://www.postgresql.org/docs/14/libpq-envars.html](https://www.postgresql.org/docs/14/libpq-envars.html). `PGPASSWORD`, if used, will be specified as a separate environment variable.
### `POSTGRES_USER`
This optional environment variable is used in conjunction with `POSTGRES_PASSWORD` to set a user and its password. This variable will create the specified user with superuser power and a database with the same name. If it is not specified, then the default user of `postgres` will be used.
Be aware that if this parameter is specified, PostgreSQL will still show `The files belonging to this database system will be owned by user "postgres"` during initialization. This refers to the Linux system user (from `/etc/passwd` in the image) that the `postgres` daemon runs as, and as such is unrelated to the `POSTGRES_USER` option. See the section titled "Arbitrary `--user` Notes" for more details.
### `POSTGRES_DB`
This optional environment variable can be used to define a different name for the default database that is created when the image is first started. If it is not specified, then the value of `POSTGRES_USER` will be used.
### `POSTGRES_INITDB_ARGS`
This optional environment variable can be used to send arguments to `postgres initdb`. The value is a space separated string of arguments as `postgres initdb` would expect them. This is useful for adding functionality like data page checksums: `-e POSTGRES_INITDB_ARGS="--data-checksums"`.
### `POSTGRES_INITDB_WALDIR`
This optional environment variable can be used to define another location for the Postgres transaction log. By default the transaction log is stored in a subdirectory of the main Postgres data folder (`PGDATA`). Sometimes it can be desireable to store the transaction log in a different directory which may be backed by storage with different performance or reliability characteristics.
**Note:** on PostgreSQL 9.x, this variable is `POSTGRES_INITDB_XLOGDIR` (reflecting [the changed name of the `--xlogdir` flag to `--waldir` in PostgreSQL 10+](https://wiki.postgresql.org/wiki/New_in_postgres_10#Renaming_of_.22xlog.22_to_.22wal.22_Globally_.28and_location.2Flsn.29)).
### `POSTGRES_HOST_AUTH_METHOD`
This optional variable can be used to control the `auth-method` for `host` connections for `all` databases, `all` users, and `all` addresses. If unspecified then [`scram-sha-256` password authentication](https://www.postgresql.org/docs/14/auth-password.html) is used (in 14+; `md5` in older releases). On an uninitialized database, this will populate `pg_hba.conf` via this approximate line:
```console
echo "host all all all $POSTGRES_HOST_AUTH_METHOD" >> pg_hba.conf
```
See the PostgreSQL documentation on [`pg_hba.conf`](https://www.postgresql.org/docs/14/auth-pg-hba-conf.html) for more information about possible values and their meanings.
**Note 1:** It is not recommended to use `trust` since it allows anyone to connect without a password, even if one is set (like via `POSTGRES_PASSWORD`). For more information see the PostgreSQL documentation on [*Trust Authentication*](https://www.postgresql.org/docs/14/auth-trust.html).
**Note 2:** If you set `POSTGRES_HOST_AUTH_METHOD` to `trust`, then `POSTGRES_PASSWORD` is not required.
**Note 3:** If you set this to an alternative value (such as `scram-sha-256`), you might need additional `POSTGRES_INITDB_ARGS` for the database to initialize correctly (such as `POSTGRES_INITDB_ARGS=--auth-host=scram-sha-256`).
### `PGDATA`
> **Important Note:** Mount the data volume at `/var/lib/postgresql/data` and not at `/var/lib/postgresql` because mounts at the latter path WILL NOT PERSIST database data when the container is re-created. The Dockerfile that builds the image declares a volume at `/var/lib/postgresql/data` and if no data volume is mounted at that path then the container runtime will automatically create an [anonymous volume](https://docs.docker.com/engine/storage/#volumes) that is not reused across container re-creations. Data will be written to the anonymous volume rather than your intended data volume and won't persist when the container is deleted and re-created.
This optional variable can be used to define another location - like a subdirectory - for the database files. The default is `/var/lib/postgresql/data`. If the data volume you're using is a filesystem mountpoint (like with GCE persistent disks), or remote folder that cannot be chowned to the `postgres` user (like some NFS mounts), or contains folders/files (e.g. `lost+found`), Postgres `initdb` requires a subdirectory to be created within the mountpoint to contain the data.
For example:
```console
$ docker run -d \
--name some-postgres \
-e POSTGRES_PASSWORD=mysecretpassword \
-e PGDATA=/var/lib/postgresql/data/pgdata \
-v /custom/mount:/var/lib/postgresql/data \
%%IMAGE%%
```
This is an environment variable that is not Docker specific. Because the variable is used by the `postgres` server binary (see the [PostgreSQL docs](https://www.postgresql.org/docs/14/app-postgres.html#id-1.9.5.14.7)), the entrypoint script takes it into account.
## Docker Secrets
As an alternative to passing sensitive information via environment variables, `_FILE` may be appended to some of the previously listed environment variables, causing the initialization script to load the values for those variables from files present in the container. In particular, this can be used to load passwords from Docker secrets stored in `/run/secrets/<secret_name>` files. For example:
```console
$ docker run --name some-postgres -e POSTGRES_PASSWORD_FILE=/run/secrets/postgres-passwd -d %%IMAGE%%
```
Currently, this is only supported for `POSTGRES_INITDB_ARGS`, `POSTGRES_PASSWORD`, `POSTGRES_USER`, and `POSTGRES_DB`.
## Initialization scripts
If you would like to do additional initialization in an image derived from this one, add one or more `*.sql`, `*.sql.gz`, or `*.sh` scripts under `/docker-entrypoint-initdb.d` (creating the directory if necessary). After the entrypoint calls `initdb` to create the default `postgres` user and database, it will run any `*.sql` files, run any executable `*.sh` scripts, and source any non-executable `*.sh` scripts found in that directory to do further initialization before starting the service.
**Warning**: scripts in `/docker-entrypoint-initdb.d` are only run if you start the container with a data directory that is empty; any pre-existing database will be left untouched on container startup. One common problem is that if one of your `/docker-entrypoint-initdb.d` scripts fails (which will cause the entrypoint script to exit) and your orchestrator restarts the container with the already initialized data directory, it will not continue on with your scripts.
For example, to add an additional user and database, add the following to `/docker-entrypoint-initdb.d/init-user-db.sh`:
```bash
#!/usr/bin/env bash
set -e
psql -v ON_ERROR_STOP=1 --username "$POSTGRES_USER" --dbname "$POSTGRES_DB" <<-EOSQL
CREATE USER docker;
CREATE DATABASE docker;
GRANT ALL PRIVILEGES ON DATABASE docker TO docker;
EOSQL
```
These initialization files will be executed in sorted name order as defined by the current locale, which defaults to `en_US.utf8`. Any `*.sql` files will be executed by `POSTGRES_USER`, which defaults to the `postgres` superuser. It is recommended that any `psql` commands that are run inside of a `*.sh` script be executed as `POSTGRES_USER` by using the `--username "$POSTGRES_USER"` flag. This user will be able to connect without a password due to the presence of `trust` authentication for Unix socket connections made inside the container.
Additionally, as of [docker-library/postgres#253](https://github.com/docker-library/postgres/pull/253), these initialization scripts are run as the `postgres` user (or as the "semi-arbitrary user" specified with the `--user` flag to `docker run`; see the section titled "Arbitrary `--user` Notes" for more details). Also, as of [docker-library/postgres#440](https://github.com/docker-library/postgres/pull/440), the temporary daemon started for these initialization scripts listens only on the Unix socket, so any `psql` usage should drop the hostname portion (see [docker-library/postgres#474 (comment)](https://github.com/docker-library/postgres/issues/474#issuecomment-416914741) for example).
## Database Configuration
There are many ways to set PostgreSQL server configuration. For information on what is available to configure, see the [PostgreSQL docs](https://www.postgresql.org/docs/14/runtime-config.html) for the specific version of PostgreSQL that you are running. Here are a few options for setting configuration:
- Use a custom config file. Create a config file and get it into the container. If you need a starting place for your config file you can use the sample provided by PostgreSQL which is available in the container at `/usr/share/postgresql/postgresql.conf.sample` (`/usr/local/share/postgresql/postgresql.conf.sample` in Alpine variants).
- **Important note:** you must set `listen_addresses = '*'`so that other containers will be able to access %%REPO%%.
```console
$ # get the default config
$ docker run -i --rm postgres cat /usr/share/postgresql/postgresql.conf.sample > my-postgres.conf
$ # customize the config
$ # run postgres with custom config
$ docker run -d --name some-postgres -v "$PWD/my-postgres.conf":/etc/postgresql/postgresql.conf -e POSTGRES_PASSWORD=mysecretpassword %%IMAGE%% -c 'config_file=/etc/postgresql/postgresql.conf'
```
- Set options directly on the run line. The entrypoint script is made so that any options passed to the docker command will be passed along to the `postgres` server daemon. From the [PostgreSQL docs](https://www.postgresql.org/docs/14/app-postgres.html#id-1.9.5.14.6.3) we see that any option available in a `.conf` file can be set via `-c`.
```console
$ docker run -d --name some-postgres -e POSTGRES_PASSWORD=mysecretpassword %%IMAGE%% -c shared_buffers=256MB -c max_connections=200
```
## Locale Customization
You can extend the Debian-based images with a simple `Dockerfile` to set a different locale. The following example will set the default locale to `de_DE.utf8`:
```dockerfile
FROM %%IMAGE%%:14.3
RUN localedef -i de_DE -c -f UTF-8 -A /usr/share/locale/locale.alias de_DE.UTF-8
ENV LANG de_DE.utf8
```
Since database initialization only happens on container startup, this allows us to set the language before it is created.
Also of note, Alpine-based variants starting with Postgres 15 support [ICU locales](https://www.postgresql.org/docs/15/locale.html#id-1.6.11.3.7). Previous Postgres versions based on alpine do *not* support locales; see ["Character sets and locale" in the musl documentation](https://wiki.musl-libc.org/functional-differences-from-glibc.html#Character-sets-and-locale) for more details.
You can set locales in the Alpine-based images with `POSTGRES_INITDB_ARGS` to set a different locale. The following example will set the default locale for a newly initialized database to `de_DE.utf8`:
```console
$ docker run -d -e LANG=de_DE.utf8 -e POSTGRES_INITDB_ARGS="--locale-provider=icu --icu-locale=de-DE" -e POSTGRES_PASSWORD=mysecretpassword %%IMAGE%%:15-alpine
```
## Additional Extensions
When using the default (Debian-based) variants, installing additional extensions (such as PostGIS) should be as simple as installing the relevant packages (see [github.com/postgis/docker-postgis](https://github.com/postgis/docker-postgis/blob/81a0b55/14-3.2/Dockerfile) for a concrete example).
When using the Alpine variants, any postgres extension not listed in [postgres-contrib](https://www.postgresql.org/docs/14/contrib.html) will need to be compiled in your own image (again, see [github.com/postgis/docker-postgis](https://github.com/postgis/docker-postgis/blob/81a0b55/14-3.2/alpine/Dockerfile) for a concrete example).
# Arbitrary `--user` Notes
As of [docker-library/postgres#253](https://github.com/docker-library/postgres/pull/253), this image supports running as a (mostly) arbitrary user via `--user` on `docker run`. As of [docker-library/postgres#1018](https://github.com/docker-library/postgres/pull/1018), this is also the case for the Alpine variants.
The main caveat to note is that `postgres` doesn't care what UID it runs as (as long as the owner of `/var/lib/postgresql/data` matches), but `initdb` *does* care (and needs the user to exist in `/etc/passwd`):
```console
$ docker run -it --rm --user www-data -e POSTGRES_PASSWORD=mysecretpassword %%IMAGE%%
The files belonging to this database system will be owned by user "www-data".
...
$ docker run -it --rm --user 1000:1000 -e POSTGRES_PASSWORD=mysecretpassword %%IMAGE%%
initdb: could not look up effective user ID 1000: user does not exist
```
The three easiest ways to get around this:
1. allow the image to use [the `nss_wrapper` library](https://cwrap.org/nss_wrapper.html) to "fake" `/etc/passwd` contents for you (see [docker-library/postgres#448](https://github.com/docker-library/postgres/pull/448) for more details)
2. bind-mount `/etc/passwd` read-only from the host (if the UID you desire is a valid user on your host):
```console
$ docker run -it --rm --user "$(id -u):$(id -g)" -v /etc/passwd:/etc/passwd:ro -e POSTGRES_PASSWORD=mysecretpassword %%IMAGE%%
The files belonging to this database system will be owned by user "jsmith".
...
```
3. initialize the target directory separately from the final runtime (with a `chown` in between):
```console
$ docker volume create pgdata
$ docker run -it --rm -v pgdata:/var/lib/postgresql/data -e POSTGRES_PASSWORD=mysecretpassword %%IMAGE%%
The files belonging to this database system will be owned by user "postgres".
...
( once it's finished initializing successfully and is waiting for connections, stop it )
$ docker run -it --rm -v pgdata:/var/lib/postgresql/data bash chown -R 1000:1000 /var/lib/postgresql/data
$ docker run -it --rm --user 1000:1000 -v pgdata:/var/lib/postgresql/data %%IMAGE%%
LOG: database system was shut down at 2017-01-20 00:03:23 UTC
LOG: MultiXact member wraparound protections are now enabled
LOG: autovacuum launcher started
LOG: database system is ready to accept connections
```
# Caveats
If there is no database when `postgres` starts in a container, then `postgres` will create the default database for you. While this is the expected behavior of `postgres`, this means that it will not accept incoming connections during that time. This may cause issues when using automation tools, such as `docker compose`, that start several containers simultaneously.
Also note that the default `/dev/shm` size for containers is 64MB. If the shared memory is exhausted you will encounter `ERROR: could not resize shared memory segment . . . : No space left on device`. You will want to pass [`--shm-size=256MB`](https://docs.docker.com/engine/reference/run/#runtime-constraints-on-resources) for example to `docker run`, or alternatively in [`docker compose`](https://docs.docker.com/compose/compose-file/05-services/#shm_size).
## Where to Store Data
**Important note:** There are several ways to store data used by applications that run in Docker containers. We encourage users of the `%%IMAGE%%` images to familiarize themselves with the options available, including:
- Let Docker manage the storage of your database data [by writing the database files to disk on the host system using its own internal volume management](https://docs.docker.com/storage/volumes/). This is the default and is easy and fairly transparent to the user. The downside is that the files may be hard to locate for tools and applications that run directly on the host system, i.e. outside containers.
- Create a data directory on the host system (outside the container) and [mount this to a directory visible from inside the container](https://docs.docker.com/storage/bind-mounts/). This places the database files in a known location on the host system, and makes it easy for tools and applications on the host system to access the files. The downside is that the user needs to make sure that the directory exists, and that e.g. directory permissions and other security mechanisms on the host system are set up correctly.
The Docker documentation is a good starting point for understanding the different storage options and variations, and there are multiple blogs and forum postings that discuss and give advice in this area. We will simply show the basic procedure here for the latter option above:
1. Create a data directory on a suitable volume on your host system, e.g. `/my/own/datadir`.
2. Start your `%%IMAGE%%` container like this:
```console
$ docker run --name some-%%REPO%% -v /my/own/datadir:/var/lib/postgresql/data -e POSTGRES_PASSWORD=mysecretpassword -d %%IMAGE%%:tag
```
The `-v /my/own/datadir:/var/lib/postgresql/data` part of the command mounts the `/my/own/datadir` directory from the underlying host system as `/var/lib/postgresql/data` inside the container, where PostgreSQL by default will write its data files.
```