From 5d24fd4453073e23a7b8cfff1972bd7bdb513180 Mon Sep 17 00:00:00 2001 From: Michael Barz Date: Thu, 2 Jun 2022 15:42:52 +0200 Subject: [PATCH] first iteration for ocis simple --- docs/ocis/guides/_index.md | 22 ++ docs/ocis/guides/ocis-and-containers.md | 44 ++++ docs/ocis/guides/ocis-local-docker.md | 319 ++++++++++++++++++++++++ 3 files changed, 385 insertions(+) create mode 100644 docs/ocis/guides/_index.md create mode 100644 docs/ocis/guides/ocis-and-containers.md create mode 100644 docs/ocis/guides/ocis-local-docker.md diff --git a/docs/ocis/guides/_index.md b/docs/ocis/guides/_index.md new file mode 100644 index 0000000000..fdfbbc10e9 --- /dev/null +++ b/docs/ocis/guides/_index.md @@ -0,0 +1,22 @@ +--- +title: "Guides" +date: 2022-06-14T16:00:00+02:00 +weight: 8 +geekdocRepo: https://github.com/owncloud/ocis +geekdocEditPath: edit/master/docs/ocis/guides +geekdocFilePath: _index.md +geekdocCollapseSection: true +--- + +{{< toc >}} + +## Step-by-step Guides + +These guides should extend the generic documentation and help admins to learn Infinite Scale through digestable "hands-on" sessions. + +### Available Guides + +oCIS deployments are super simple, yet there are many configurations possible for advanced setups. + +- {{< icon "docker" >}} [Discover oCIS with Docker]({{< ref "ocis-local-docker" >}}) - configure domain, certificates and port + diff --git a/docs/ocis/guides/ocis-and-containers.md b/docs/ocis/guides/ocis-and-containers.md new file mode 100644 index 0000000000..b00ecc3ca7 --- /dev/null +++ b/docs/ocis/guides/ocis-and-containers.md @@ -0,0 +1,44 @@ +--- +title: "oCIS and Containers" +date: 2022-06-14T16:00:00+02:00 +weight: 5 +geekdocRepo: https://github.com/owncloud/ocis +geekdocEditPath: edit/master/docs/ocis/guides +geekdocFilePath: ocis-and-conatiners.md +geekdocCollapseSection: true +--- + +## Cloud Native + +Why do we recommend to work with containers? + +{{< columns >}} + +### {{< icon "scale-balanced" >}}   Lightweight + +Containers are more lightweight than VMs. It is easier to work with shared volumes and networks because they are isolated from the host system. +<---> + +### {{< icon "shield-halved" >}}   Dependencies + +The container images have all dependencies installed and the maintainer takes care for keeping them up-to-date. + +<---> + +### {{< icon "gauge-high" >}}   Scaling + +In addition to that, containers help with scaling. You can run multiple instances of one container and distribute them across hosts. + +{{< /columns >}} + +## Docker compose + +For oCIS deployments you often need multiple services. These services need to share resources like volumes and networks. If you do not use any orchestration tool, you would end up writing bash scripts to create and update containers and volumes and connect them via networks. This is what orchestration tools like docker compose can do for you. You define a service mesh using .yaml files and the tool tries to run and maintain that. You gain more value and a version history by using a version control system. Your deployment configuration is fully written down as a spec and you will never touch any system directly and change the config manually. + +## Kubernetes + +Containers are also used in [kubernetes](https://kubernetes.io/). Kubernetes is part of a huge ecosystem and is founded on best-of-breed practises to orchestrate large scale container applications and services. + +## oCIS and Containers + +oCIS was developed as microservices. We do not scale the whole system as a monolith but we scale the individual services. diff --git a/docs/ocis/guides/ocis-local-docker.md b/docs/ocis/guides/ocis-local-docker.md new file mode 100644 index 0000000000..4e08b56fda --- /dev/null +++ b/docs/ocis/guides/ocis-local-docker.md @@ -0,0 +1,319 @@ +--- +title: "Discover oCIS with Docker" +date: 2022-06-14T16:00:00+02:00 +weight: 8 +geekdocRepo: https://github.com/owncloud/ocis +geekdocEditPath: edit/master/docs/ocis/guides +geekdocFilePath: ocis-local-docker.md +geekdocCollapseSection: true +--- + +{{< toc >}} + +## Prerequisites + +- Local docker installation (e.g. Docker for Desktop) +- Check [oCIS and Containers]({{< ref "ocis-and-containers" >}}) + +## Start oCIS with docker compose + +### Create the project + +Use the following skeleton as a docker-compose.yml: + +```bash +mkdir simple-ocis && \ +cd simple-ocis && \ +touch docker-compose.yml +``` + +Copy the following file content into `docker-compose.yml` and save it. + +```yaml +version: "3.7" + +services: + ocis: + image: owncloud/ocis:latest + environment: + # INSECURE: needed if oCIS / Traefik is using self generated certificates + OCIS_INSECURE: "true" + + # OCIS_URL: the external domain / ip address of oCIS (with protocol, must always be https) + OCIS_URL: "https://localhost:9200" + + # OCIS_LOG_LEVEL: error / info / ... / debug + OCIS_LOG_LEVEL: info +``` + +### Initialize + +Run ocis init to create a config + +```bash +docker run --rm -it -v $(pwd):/etc/ocis/ owncloud/ocis:latest init +``` + +You will get the following output: + +```txt {hl_lines=[9]} +Do you want to configure Infinite Scale with certificate checking disabled? + This is not recommended for public instances! [yes | no = default] yes + +========================================= + generated OCIS Config +========================================= + configpath : /etc/ocis/ocis.yaml + user : admin + password : t3p4N0jJ47LbhpQ04s9W%u1$d2uE3Y.3 +``` + +Check your local folder. We just generated a default ocis configuration file with random passwords and secrets. + +```bash +ls # list the current folder +docker-compose.yml ocis.yaml # ocis.yaml has been generated +``` + +Run `cat ocis.yaml` + +```yaml {linenos=table,hl_lines=[19]} +token_manager: + jwt_secret: X35rffWpS9BR.=^#LDt&z3ykYOd7h@w* +machine_auth_api_key: -0$4ieu5+t6HD6Ui^0PpKU6B0qxisv.m +system_user_api_key: oVxICwMR9YcKXTau+@pqKZ0EO-OHz8sF +transfer_secret: e%3Sda=WFBuy&ztBUmriAbBR$i2CmaDv +system_user_id: b7d976a1-7300-4db7-82df-13502d6b5e18 +admin_user_id: c59a6ae9-5f5e-4eef-b82e-0e5c34f93e52 +graph: + spaces: + insecure: false + identity: + ldap: + bind_password: wElKpGjeH0d.E4moXh=.dc@s2CtB0vy% +idp: + ldap: + bind_password: Ft2$2%#=6Mi22@.YPkhh-c6Kj=3xBZAb +idm: + service_user_passwords: + admin_password: t3p4N0jJ47LbhpQ04s9W%u1$d2uE3Y.3 + idm_password: wElKpGjeH0d.E4moXh=.dc@s2CtB0vy% + reva_password: pJAdZ2fU!SFKgcdDPRW%ruIiNM6GnN1D + idp_password: Ft2$2%#=6Mi22@.YPkhh-c6Kj=3xBZAb +proxy: + insecure_backends: false +frontend: + archiver: + insecure: false +auth_basic: + auth_providers: + ldap: + bind_password: pJAdZ2fU!SFKgcdDPRW%ruIiNM6GnN1D +auth_bearer: + auth_providers: + oidc: + insecure: false +users: + drivers: + ldap: + bind_password: pJAdZ2fU!SFKgcdDPRW%ruIiNM6GnN1D +groups: + drivers: + ldap: + bind_password: pJAdZ2fU!SFKgcdDPRW%ruIiNM6GnN1D +storage_system: + data_provider_insecure: false +storage_users: + data_provider_insecure: false +ocdav: + insecure: false +thumbnails: + thumbnail: + transfer_secret: z-E%G8MTeFpuT-ez2o8BjfnG1Jl2yLLm + webdav_allow_insecure: false + cs3_allow_insecure: false +``` + +{{< hint type=tip title="Admin password" >}} +**Password initialisation**\ +During the run of `./ocis init`, the password for the `admin` user has been set to a random string. + +You can override that later by setting `IDM_ADMIN_PASSWORD=secret`. The ENV variable setting always overrides the config file. +{{< /hint >}} + +### Mount the config file + +Add the config file as a bind mount. + +```yaml + volumes: + # mount the ocis config file inside the container + - "./ocis.yaml:/etc/ocis/ocis.yaml" +``` + +### Apply the changes + +```bash +docker compose up -d +``` + +The service should be running. + +```bash +docker compose ps +NAME COMMAND SERVICE STATUS PORTS +simple-ocis-ocis-1 "/usr/bin/ocis server" ocis running 9200/tcp +``` + +### Open the port 9200 to the outside + +```yaml +ports: + - 9200:9200 +``` + +Add a port mapping to your docker compose file and run `docker compose up -d` again. You should now be able to access and log in. You will get a warning from your browser that the connection is not safe because we are using a self-signed certificate. Accept this warning message to continue. Use the user `admin` and the password which has been initialized before. + +Congratulations! You have successfully set up a simple Infinite Scale locally. + +{{< hint type=tip title="Docker Compose Helps you" >}} +**docker compose up**\ +You do not need to shut down your service to apply changes from the docker-compose.yml file. Running `docker compose up -d` again is enough. Docker compose always tries to bring all services to the desired state. + +**docker compose ps**\ +This gives you a status of the services of the project. + +**docker compose exec \ \**\ +This command is handy to run specific commands inside your service. Try `docker compose exec ocis ocis version`. +{{< /hint >}} + +### Persist data, restart and logging + +The key to a successful container setup is the persistance of the application data to make the data survive a re-boot. Docker normally uses [volumes](https://docs.docker.com/storage/volumes/) for this purpose. A volume can either be a "named volume" which are completely managed by docker and have many advantages (see the linked docker documentation), or "bind mounts" which are uing the directory structure and OS of the host system. In our example we already use a bind mount for the config file. We will now add a named volume for the oCIS data directory. + +This is the way we should configure the ocis service: + +```yaml + volumes: + # mount the ocis config file inside the container + - "./ocis.yaml:/etc/ocis/ocis.yaml" + # short syntax for using a named volume + # in the form : + # use a named volume for the ocis data directory + - "ocis-data:/var/lib/ocis" + # or the more verbose syntax + #- type: volume + # source: ocis-data # name of the volume + # target: /var/lib/ocis # the mount path inside the container +``` + +The docker-compose.yml needs to declare the named volumes globally, add this at the bottom of the file: + +```yaml +# https://docs.docker.com/compose/compose-file/compose-file-v3/#volumes +# this declares the named volume with all default settings +# you can also see the volume when running `docker volume list` +volumes: + ocis-data: +``` + +Now let us configure the restart policy and the logging settings for the ocis service: + +```yaml + # https://docs.docker.com/compose/compose-file/compose-file-v3/#restart + restart: always # or on-failure / unless-stopped + + # https://docs.docker.com/config/containers/logging/configure/ + # https://docs.docker.com/compose/compose-file/compose-file-v3/#logging + # the default log driver does no log rotation + # you can switch to the "local" log driver which does rotation by default + logging: + driver: local + # otherwise you could specify log rotation exlicitely + # driver: "json-file" # this is the default driver + # options: + # max-size: "200k" # limit the size of the log file + # max-file: "10" # limit the count of the log files +``` + +Apply your changes! Just run `docker compose up -d` again. + +Now you have an oCIS which will survive reboots, restart automatically and has log rotation by default. + +Access the logs via `docker compose logs -f` and do some actions in the frontend to see the effect. Create data by uploading files and adding more users. Then run `docker compose down` to shut oCIS down. Start it again `docker compose up -d`, log in again and check that your data has survived the reboot. + +### Pin the oCIS version + +Last but not least, it is never a good idea to use the `latest` docker tag. Pin your container image to a released version. + +```yaml + image: owncloud/ocis:latest@sha256:5ce3d5f9da017d6760934448eb207fbaab9ceaf0171b4122e791e292f7c86c97 + # the latest tag is not recommended, because you don't know which version you'll get + # but even if you use `owncloud/ocis:1.16.0` you cannot be sure that you'll get + # the exact same image if you pull it at a later point in time (because docker image tags are not immutable). + # To be 100% that you always get the same image, you can pin the digest (hash) of the + # image. If you do a `docker pull owncloud/ocis:latest`, it also will also show you the digest. + # see also https://docs.docker.com/engine/reference/commandline/images/#list-image-digests +``` + +## Final solution + +If you have completed this guide, your docker-compose.yml should look like the following example: + +{{< expand "Solution" "..." >}} +```yaml +version: "3.7" + +services: + ocis: + image: owncloud/ocis:latest@sha256:5ce3d5f9da017d6760934448eb207fbaab9ceaf0171b4122e791e292f7c86c97 + # the latest tag is not recommended, because you don't know which version you'll get + # but even if you use `owncloud/ocis:1.16.0` you cannot be sure that you'll get + # the exact same image if you pull it at a later point in time (because docker image tags are not immutable). + # To be 100% that you always get the same image, you can pin the digest (hash) of the + # image. If you do a `docker pull owncloud/ocis:latest`, it also will also show you the digest. + # see also https://docs.docker.com/engine/reference/commandline/images/#list-image-digests + environment: + # INSECURE: needed if oCIS / Traefik is using self generated certificates + OCIS_INSECURE: "true" + + # OCIS_URL: the external domain / ip address of oCIS (with protocol, must always be https) + OCIS_URL: "https://localhost:9200" + + # OCIS_LOG_LEVEL: error / info / ... / debug + OCIS_LOG_LEVEL: info + volumes: + # mount the ocis config file inside the container + - "./ocis.yaml:/etc/ocis/ocis.yaml" + # short syntax for using a named volume + # in the form : + # use a named volume for the ocis data directory + - "ocis-data:/var/lib/ocis" + # or the more verbose syntax + #- type: volume + # source: ocis-data # name of the volume + # target: /var/lib/ocis # the mount path inside the container + ports: + - 9200:9200 + # https://docs.docker.com/compose/compose-file/compose-file-v3/#restart + restart: always # or on-failure / unless-stopped + + # https://docs.docker.com/config/containers/logging/configure/ + # https://docs.docker.com/compose/compose-file/compose-file-v3/#logging + # the default log driver does no log rotation + # you can switch to the "local" log driver which does rotation by default + logging: + driver: local + # otherwise you could specify log rotation exlicitely + # driver: "json-file" # this is the default driver + # options: + # max-size: "200k" # limit the size of the log file + # max-file: "10" # limit the count of the log files + +# https://docs.docker.com/compose/compose-file/compose-file-v3/#volumes +# this declares the named volume with all default settings +# you can also see the volume when running `docker volume list` +volumes: + ocis-data: +``` +{{< /expand >}}