diff --git a/docs/modules/ROOT/assets/images/how-to/appflow/appflow-create-app-part1.png b/docs/modules/ROOT/assets/images/how-to/appflow/appflow-create-app-part1.png new file mode 100644 index 00000000..d6a29d37 Binary files /dev/null and b/docs/modules/ROOT/assets/images/how-to/appflow/appflow-create-app-part1.png differ diff --git a/docs/modules/ROOT/assets/images/how-to/appflow/appflow-create-app-part2.png b/docs/modules/ROOT/assets/images/how-to/appflow/appflow-create-app-part2.png new file mode 100644 index 00000000..a6d3cb6c Binary files /dev/null and b/docs/modules/ROOT/assets/images/how-to/appflow/appflow-create-app-part2.png differ diff --git a/docs/modules/ROOT/assets/images/how-to/appflow/appflow-download-pipeline-secrets.png b/docs/modules/ROOT/assets/images/how-to/appflow/appflow-download-pipeline-secrets.png new file mode 100644 index 00000000..ba4c0ff6 Binary files /dev/null and b/docs/modules/ROOT/assets/images/how-to/appflow/appflow-download-pipeline-secrets.png differ diff --git a/docs/modules/ROOT/assets/images/logos/nextcloud.svg b/docs/modules/ROOT/assets/images/logos/nextcloud.svg new file mode 100644 index 00000000..cc0cdb65 --- /dev/null +++ b/docs/modules/ROOT/assets/images/logos/nextcloud.svg @@ -0,0 +1,3 @@ + + +image/svg+xml \ No newline at end of file diff --git a/docs/modules/ROOT/nav.adoc b/docs/modules/ROOT/nav.adoc index ae6ad14c..f2295d97 100644 --- a/docs/modules/ROOT/nav.adoc +++ b/docs/modules/ROOT/nav.adoc @@ -60,6 +60,7 @@ ** xref:tutorials/demo-app/mastodon.adoc[Mastodon] ** xref:tutorials/demo-app/takahe.adoc[Takahē] ** xref:tutorials/demo-app/gitea.adoc[Gitea] +** xref:tutorials/demo-app/appcat-nextcloud.adoc[Nextcloud] * Databases ** xref:how-to/install-postgres-db-helm.adoc[PostgreSQL] diff --git a/docs/modules/ROOT/pages/tutorials/demo-app/appcat-nextcloud.adoc b/docs/modules/ROOT/pages/tutorials/demo-app/appcat-nextcloud.adoc new file mode 100644 index 00000000..2d85e5f5 --- /dev/null +++ b/docs/modules/ROOT/pages/tutorials/demo-app/appcat-nextcloud.adoc @@ -0,0 +1,153 @@ += Deploy https://products.vshn.ch/appcat/nextcloud.html[VSHNNextcloud] to {product} + +image:logos/nextcloud.svg[role="related thumb right",alt="Service logo nextcloud",width=120,height=120] +This tutorial explains how to run https://nextcloud.com/[Nextcloud] +with link:++https://products.vshn.ch/appcat/nextcloud.html[VSHNNextcloud]++[VSHNNextcloud] on {product} using the pipeline from https://github.com/vshn/appflow-demo[Appflow]. + +== Requirements + +* Access to {product} +* A https://github.com[GitHub] account + +== Add the https://products.vshn.ch/appcat/index.html[VSHN Application Catalog] claim + +To provision Nextcloud, we need a https://products.vshn.ch/appcat/nextcloud.html[VSHNNextcloud] claim. +The documentation for VSHNNextcloud can be found here: https://docs.appcat.ch/vshn-managed/nextcloud/index.html[Nextcloud by VSHN]. +We start with a very simple setup: + +.VSHNNextcloud +[source,yaml] +---- +apiVersion: vshn.appcat.vshn.io/v1 +kind: VSHNNextcloud +metadata: + name: appcat-demo-nextcloud-appuio-simple # <1> + namespace: vshn2-demo-nextcloud-appuio-simple-prod # <2> +spec: + parameters: + service: + fqdn: + - appuio-nextcloud-demo.apps.cloudscale-lpg-2.appuio.cloud # <3> + version: "32" # <4> + size: # <5> + plan: standard-2 + writeConnectionSecretToRef: + name: nextcloud-creds # <6> +---- +<1> Instance name +<2> The namespace where the object will be created +<3> Your fully qualified domain name. +You should be able to change the DNS record for this domain. +<4> Nextcloud version +<5> Size of the Nextcloud instance. +See https://docs.appcat.ch/vshn-managed/nextcloud/plans.html[Plans and Sizing] +for more information. +<6> Secret where the connection details are provisioned. +No secret with this name should exist in this namespace before creation. + +== Put the claim under version control + +To keep track of what's deployed, we put this claim into our Git repository. +For that, you need to create +a https://github.com/new[new Git repository] on GitHub. +Now, we store the claim from before under `helm/templates/nextcloud.yaml`. +You can see the result in the +https://github.com/vshn/appcat-demo-nextcloud-appuio-simple/tree/main/helm/templates[example repository]. +We also need some boilerplate for Helm; +you can also find this in the +https://github.com/vshn/appcat-demo-nextcloud-appuio-simple/tree/main/helm[example repository]. + +== Deploy the claim + +If you are a VSHN customer, you can generate the pipeline to deploy Nextcloud in xref:#appflow-helm[AppFlow]. + +Otherwise, you can copy the `.github/workflows` directory from the +https://github.com/vshn/appcat-demo-nextcloud-appuio-simple/tree/main/.github[example repository] +and adapt it where needed. +For the pipeline to work, you need to add a kubeconfig to your pipeline. +First, you need to make sure you have the `oc` utility. +You can download it from th +https://console.cloudscale-lpg-2.appuio.cloud/command-line-tools[OpenShift console command line tools]. + +.Generate kubeconfig for pipeline +[source,shell] +---- +KUBECONFIG=./config-for-pipeline +oc login --web --server https://api.${zone}.cloud:6443 +cat $KUBECONFIG +---- + +You can find the exact URL of your chosen zone in the +https://portal.appuio.cloud/zones[{product} Portal]. + +This token is only valid for a short time. +To create a kubeconfig with a longer lifetime you can either use +xref:#appflow-helm[AppFlow] +or follow the +https://docs.appuio.cloud/user/how-to/use-github-actions.html#_4_configure_secrets[DevOps and CI/CD docs for github]. + +Now you need to add this kubeconfig to the GitHub *secrets*. You find them under `Settings → Environments → choose environment → (+) Add secret`. In this case, the environment name is `prod`. +The kubeconfig must be stored as secret with the name `KUBECONFIG_PROD`. + +We now have the pipeline and a minimal claim. But there are some steps missing. + +== Best Practices + +To follow best practices for your Nextcloud deployment, you need to configure the following settings: + +.VSHNNextcloud: best practice +[source,yaml] +---- +apiVersion: vshn.appcat.vshn.io/v1 +kind: VSHNNextcloud +metadata: + name: appcat-demo-nextcloud-appuio-simple + namespace: vshn2-demo-nextcloud-appuio-simple-prod +spec: + parameters: + backup: + retention: + keepDaily: 6 # <1> + instances: 1 # <2> + maintenance: # <3> + dayOfWeek: wednesday + timeOfDay: '23:42:18' + monitoring: + email: your@email.com # <4> + service: + fqdn: + - appuio-nextcloud-demo.apps.cloudscale-lpg-2.appuio.cloud + version: "32" + postgreSQLParameters: + encryption: + enabled: true + service: + majorVersion: "17" # <5> + monitoring: + email: your@email.com # <6> + instances: 1 # <7> + size: + plan: standard-2 + disk: 16Gi # <8> + writeConnectionSecretToRef: + name: nextcloud-creds +---- +<1> The number of daily backups to keep. +<2> Set to a value greater than 1 if you want to run Nextcloud with High Availability and update it without downtime. +<3> When the maintenance job should run. +<4> The email address where user alerts for Nextcloud should be sent. +<5> The major version for the PostgreSQL instance. Start with the most recent major version. +<6> The email address where user alerts for the PostgreSQL instance are sent. +<7> Set to a value greater than 1 if you want to run PostgreSQL with High Availability and update it without downtime. +<8> The desired disk space for your Nextcloud instance. This can only be increased later. + +After you have configured all these settings, you can deploy your Nextcloud. +You will find the credentials to log in to your Nextcloud in the secret you specified previously. +It takes a while until the VSHNNextcloud is ready +and it may take even longer until the secret with the credentials is available. +You can retrieve this secret using the OpenShift console under +https://console.cloudscale-lpg-2.appuio.cloud/k8s/all-namespaces/core%7Ev1%7ESecret[Workloads > Secret] +(Here for cloudscale). +If you used the provided link, you will need to choose the correct project in the dropdown menu. + +include::partial$appflow-helm-only.adoc[AppFlow] diff --git a/docs/modules/ROOT/pages/tutorials/demo-app/index.adoc b/docs/modules/ROOT/pages/tutorials/demo-app/index.adoc index f3c5029c..1aa3c616 100644 --- a/docs/modules/ROOT/pages/tutorials/demo-app/index.adoc +++ b/docs/modules/ROOT/pages/tutorials/demo-app/index.adoc @@ -38,6 +38,11 @@ image:logos/gitea.svg[alt="Gitea logo",width=100,height=50,link="https://gitea.i |xref:tutorials/demo-app/gitea.adoc[Gitea] |https://docs.appcat.ch/exoscale-dbaas/mysql/index.html[ExoscaleMySQL^] +| +image:logos/nextcloud.svg[alt="Nextcloud logo",width=100,height=50,link="https://nextcloud.com/",window=_blank] +|xref:tutorials/demo-app/appcat-nextcloud.adoc[Nextcloud] +|https://docs.appcat.ch/vshn-managed/nextcloud/index.html[Cloudscale Nextcloud^] + |=== Thanks to https://bitnami.com/[Bitnami^] for providing very robust application images, which we're making use of in most of our examples. diff --git a/docs/modules/ROOT/partials/appflow-helm-only.adoc b/docs/modules/ROOT/partials/appflow-helm-only.adoc new file mode 100644 index 00000000..ae9fb614 --- /dev/null +++ b/docs/modules/ROOT/partials/appflow-helm-only.adoc @@ -0,0 +1,31 @@ +[#appflow-helm] +== Create an application and environment with link:++https://github.com/vshn/appflow-demo[Appflow]++[AppFlow] + +Navigate to https://control.vshn.net/appflow/apps[AppFlow] on the https://control.vshn.net/[VSHN Portal] and click on `Create App with Environment`. + +.AppFlow: Create App +image::how-to/appflow/appflow-create-app-part1.png[AppFlow create App 1] +- Name of your application: The name of your application. +This will be the first part of the namespace name that will be created. +- Name of environment: The name of the environment. +This will be the second part of the namespace name that will be created. +- Cluster: The cluster you want to deploy to. +- APPUiO Organization: The APPUiO Organization you want to use for +the deployment. + +image::how-to/appflow/appflow-create-app-part2.png[AppFlow create App 2] +Important settings here are: + +- Branches to build: Deploy only the main branch. We'll keep it simple +and deploy only the main branch to the single prod environment. +- Deploy using helm-chart: We use a Helm chart to deploy the resources. +To allow for other files in the repository, +the Helm chart is located in the `helm` directory. +- Automatic deployment: A push to the main branch should trigger the deployment of changes. + +You should then see the created application with its environment, in this case, `prod`. + +.AppFlow: Download pipeline and CI variables +image::how-to/appflow/appflow-download-pipeline-secrets.png[AppFlow setup CI] +<1> Download GitHub workflow +<2> Show CI variables \ No newline at end of file