mirror/opencloud
1
0
Fork 0
mirror of https://github.com/opencloud-eu/opencloud.git synced 2026-01-12 23:29:57 -06:00
Code Issues Packages Projects Releases Wiki Activity

Merge pull request #3918 from owncloud/guide-1

Browse Source 
[docs-only] first iteration for ocis simple guide
This commit is contained in:
Michael Barz
2022-06-14 17:57:24 +02:00
committed by GitHub
parent b984b51540 5d24fd4453
commit 35007ee26b
3 changed files with 385 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

22
docs/ocis/guides/_index.md Normal file
View File

@@ -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

44
docs/ocis/guides/ocis-and-containers.md Normal file
View File

@@ -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" >}} &nbsp; 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" >}} &nbsp; Dependencies
The container images have all dependencies installed and the maintainer takes care for keeping them up-to-date.
<--->
### {{< icon "gauge-high" >}} &nbsp; 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.

319
docs/ocis/guides/ocis-local-docker.md Normal file
View File

@@ -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 <https://localhost:9200> 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 \<service name\> \<command\>**\
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 <volume name>:<mount path in the container>
# 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 <volume name>:<mount path in the container>
# 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 >}}