| giolekva | 34eef55 | 2021-12-04 22:32:47 +0400 | [diff] [blame] | 1 | # PCloud Installation Instructions |
| 2 | |
| 3 | ## Overview |
| 4 | PCloud is multitenant by default and its services are split into two **infrastructure** and **application** categories. |
| 5 | Infrastructure services are shared among all PCloud instances installed on the same cluster of servers, while application services are installed separately for each instance. |
| 6 | |
| 7 | PCloud runs on top of Kubernetes, bellow are listed all namespaces needed for healthy setup with services running inside them. |
| 8 | |
| 9 | Infrastructure: |
| 10 | * **pcloud-networking-metallb**: runs [metallb](https://metallb.universe.tf) so we can use LoadBalancer type services when running PCloud on on-prem hardware. |
| 11 | * **pcloud-ingress-public**: runs [ingress-nginx](https://github.com/kubernetes/ingress-nginx) to expose services outside of the cluster. |
| 12 | * **pcloud-cert-manager**: runs [cert-manager](https://cert-manager.io) to automate generating SSL certificates for services. |
| 13 | * **pcloud-nebula-controller**: runs [nebula](https://github.com/slackhq/nebula) [controller](https://github.com/giolekva/pcloud/tree/main/core/nebula/controller) to automate signing certificates for VPN mesh network nodes. |
| 14 | * **pcloud-oauth2-manager**: runs [Ory Hydra Maester](https://github.com/ory/hydra-maester) to automate generating registering OAuth2 clients. |
| 15 | * **pcloud-mail-gateway**: runs instance of [maddy](https://maddy.email) as a SMTP MX gateway routing incoming emails to proper PCloud instances and routing outgoing emails to the *world*. |
| 16 | * **longhorn-system**: runs [Longhorn](https://longhorn.io) to support persistent volumens. |
| 17 | * **pcloud-kubed**: runs [kubed](https://github.com/kubeops/config-syncer) to automatically sync wildcard and root level domain certificates across all namespaces of one PCloud instance. |
| 18 | |
| 19 | Applications, assuming PCloud instance is named **example**: |
| 20 | * **example-ingress-private**: runs another instance of ingress-nginx to handle traffic coming from private mesh network. |
| 21 | * **example-core-auth**: runs [Ory Kratos](https://www.ory.sh/kratos/docs/) for user authentication, [Ory Hydra](https://www.ory.sh/hydra/docs/) to handle OAuth2 and OpenID connect, and [PCloud serlfservice UI](https://github.com/giolekva/pcloud/tree/main/core/auth/ui) which provides registration/authentication UI. |
| 22 | * **example-app-pihole**: runs [Pi-hole](https://pi-hole.net) to provide DNS based network wide Ad Blocker for private mesh network nodes.x |
| 23 | * **example-app-maddy**: runs another instance of maddy to provide SMTP and IMAP services to users. |
| 24 | * **example-app-vaultwarden**: runs [Vaultwarden](https://github.com/dani-garcia/vaultwarden) which is alternate implementation of Bitwarden Server API to provide users secure password manager. |
| 25 | * **example-app-matrix**: runs [Matrix](https://matrix.org) [Synapse](https://github.com/matrix-org/synapse) homeserver. |
| 26 | * **example**: holds information about above mentioned namespaces. |
| 27 | |
| 28 | ## Setup instructions |
| 29 | ### Prerequisites: |
| 30 | * Installation scripts expect working Kubernetes cluster. |
| 31 | * Helm 3: https://helm.sh/docs/intro/install/ |
| 32 | * Helm diff plugin: https://github.com/databus23/helm-diff#install |
| 33 | * Helm secrets plugin: https://github.com/jkroepke/helm-secrets/wiki/Installation |
| 34 | * Mozilla SOPS: https://github.com/mozilla/sops#1download |
| 35 | * helmfile: https://github.com/roboll/helmfile#installation |
| 36 | |
| 37 | ### Infrastructure: |
| 38 | First update mail-gateway domains section in `pcloud/helmfile/infra/helmfile.yaml` |
| 39 | * **name**: domain name |
| 40 | * **namespace**: **bobo**-app-maddy |
| 41 | * **mx**: mail.<same domain name as above> |
| 42 | * **certificateissuer**: **bobo**-public |
| 43 | |
| 44 | Run: |
| 45 | ```shell |
| 46 | cd pcloud/helmfile/infra/ |
| 47 | helmfile -e prod apply --skip-diff-on-install |
| 48 | ``` |
| 49 | |
| 50 | ### Applications: |
| 51 | First configure `.sops.yaml` file in pcloud/helmfile/apps directory. |
| 52 | |
| 53 | Then create `secrets.bobo.yaml` file with for keys: |
| 54 | * **gandiAPIToken**: your Gandi API token |
| 55 | * **piholeOAuth2ClientSecret**: generate using https://github.com/oauth2-proxy/oauth2-proxy/blob/master/docs/docs/configuration/overview.md#generating-a-cookie-secret |
| 56 | * **piholeOAuth2CookieSecret**: ditto |
| 57 | * **matrixOAuth2ClientSecret**: ditto |
| 58 | |
| 59 | Next add new environment in `pcloud/helmfile/apps/helmfile.yaml` |
| 60 | ```yaml |
| 61 | bobo: |
| 62 | secrets: |
| 63 | - secrets.bobo.yaml |
| 64 | values: |
| 65 | - pcloudEnvName: pcloud |
| 66 | - id: bobo |
| 67 | - namespacePrefix: bobo- |
| 68 | - domain: <repeat primary domain from infra/helmfile.yaml> |
| 69 | - contactEmail: <your email address> |
| 70 | - certManagerNamespace: pcloud-cert-manager |
| 71 | - mxHostname: <repeat primary domain mx hostname from infra/helmfile.yaml> |
| 72 | - mailGatewayAddress: "tcp://maddy.pcloud-mail-gateway.svc.cluster.local:587" |
| 73 | - matrixStorageSize: 100Gi |
| 74 | - publicIP: <clusters public IP> |
| 75 | - lighthouseMainIP: 111.0.0.1 |
| 76 | - lighthouseMainPort: 4242 |
| 77 | - lighthouseAuthUIIP: 111.0.0.2 |
| 78 | ``` |
| 79 | |
| 80 | Run **(you might have to run this step multiple times :)** |
| 81 | ```shell |
| 82 | cd pcloud/helmfile/apps/ |
| 83 | helmfile -e bobo apply --skip-diff-on-install |
| 84 | ``` |