From 56a4292f4fcca2e7ad8b41b42abebe2f2af93df0 Mon Sep 17 00:00:00 2001 From: MaximUltimatum Date: Sat, 7 Dec 2024 14:26:18 -0500 Subject: [PATCH 1/3] Adding kustomize documentation --- documentation/docs/install/kustomize.md | 56 +++++++ .../docs/install/kustomize_example.md | 155 ++++++++++++++++++ 2 files changed, 211 insertions(+) create mode 100644 documentation/docs/install/kustomize.md create mode 100644 documentation/docs/install/kustomize_example.md diff --git a/documentation/docs/install/kustomize.md b/documentation/docs/install/kustomize.md new file mode 100644 index 00000000..3f972be6 --- /dev/null +++ b/documentation/docs/install/kustomize.md @@ -0,0 +1,56 @@ +# Kustomize (k8s) + +_AdventureLog can be run inside a kubernetes cluster using [kustomize](https://kustomize.io/)._ + +## Prerequisites + +A working kubernetes cluster. AdventureLog has been tested on k8s, but any Kustomize-capable flavor should be easy to use. + +## Cluster Routing +Because the AdventureLog backend must be reachable by **both** the web browser and the AdventureLog frontend, k8s-internal routing mechanisms traditional for standing up other similar applications **cannot** be used. + +In order to host AdventureLog in your cluster, you must therefor configure an internally and externally resolvable ingress that routes to your AdventureLog backend container. + +Once you have made said ingress, set `PUBLIC_SERVER_URL` and `PUBLIC_URL` env variables below to the url of that ingress. + +## Tailscale and Headscale +Many k8s homelabs choose to use [Tailscale](https://tailscale.com/) or similar projects to remove the need for open ports in your home firewall. + +The [Tailscale k8s Operator](https://tailscale.com/kb/1185/kubernetes/) will set up an externally resolvable service/ingress for your AdventureLog instance +but it will fail to resolve internally. + +You must [expose tailnet IPs to your cluster](https://tailscale.com/kb/1438/kubernetes-operator-cluster-egress#expose-a-tailnet-https-service-to-your-cluster-workloads) so the AdventureLog pods can resolve them. + +## Getting Started + +Take a look at the [example config](kustomize_example.md) and modify it for your usecase. + +## Environment Variables + +Look at the [environment variable summary](docker.md#configuration) in the docker install section to see available and required configuration options. + +### Frontend Container (web) + +| Name | Required | Description | Default Value | +| ------------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------- | +| `PUBLIC_SERVER_URL` | Yes | What the frontend SSR server uses to connect to the backend. | http://server:8000 | +| `ORIGIN` | Sometimes | Not needed if using HTTPS. If not, set it to the domain of what you will acess the app from. | http://localhost:8015 | +| `BODY_SIZE_LIMIT` | Yes | Used to set the maximum upload size to the server. Should be changed to prevent someone from uploading too much! Custom values must be set in **kiliobytes**. | Infinity | + +### Backend Container (server) + +| Name | Required | Description | Default Value | +| ----------------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------- | +| `PGHOST` | Yes | Databse host. | db | +| `PGDATABASE` | Yes | Database. | database | +| `PGUSER` | Yes | Database user. | adventure | +| `PGPASSWORD` | Yes | Database password. | changeme123 | +| `DJANGO_ADMIN_USERNAME` | Yes | Default username. | admin | +| `DJANGO_ADMIN_PASSWORD` | Yes | Default password, change after inital login. | admin | +| `DJANGO_ADMIN_EMAIL` | Yes | Default user's email. | admin@example.com | +| `PUBLIC_URL` | Yes | This needs to match the outward port of the server and be accessible from where the app is used. It is used for the creation of image urls. | 'http://localhost:8016' | +| `CSRF_TRUSTED_ORIGINS` | Yes | Need to be changed to the orgins where you use your backend server and frontend. These values are comma seperated. | http://localhost:8016 | +| `FRONTEND_URL` | Yes | This is the publically accessible url to the **frontend** container. This link should be accessable for all users. Used for email generation. | 'http://localhost:8015' | + + +Enjoy AdventureLog! 🎉 diff --git a/documentation/docs/install/kustomize_example.md b/documentation/docs/install/kustomize_example.md new file mode 100644 index 00000000..9396c326 --- /dev/null +++ b/documentation/docs/install/kustomize_example.md @@ -0,0 +1,155 @@ +```yaml +apiVersion: apps/v1 +kind: Deployment +metadata: + name: example-name + labels: + app: adventure +spec: + replicas: 1 + selector: + matchLabels: + app: adventure + template: + metadata: + name: adventure + labels: + app: adventure + spec: + volumes: + - name: adventure-journal + persistentVolumeClaim: + claimName: adventure-journal-pvc + - name: adventure-journal-db + persistentVolumeClaim: + claimName: adventure-journal-db-pvc + containers: + - name: adventure-frontend + image: ghcr.io/seanmorley15/adventurelog-frontend:latest + imagePullPolicy: IfNotPresent + ports: + - containerPort: 3000 + env: + - name: PUBLIC_SERVER_URL + value: "http://internally-and-externally.reachable.io:80" + - name: ORIGIN + value: "http://url-typed-into-browser.io:80" + - name: BODY_SIZE_LIMIT + value: "Infinity" + + - name: adventure-db + image: postgis/postgis:15-3.3 + imagePullPolicy: IfNotPresent + ports: + - containerPort: 5432 + volumeMounts: + - name: adventure-journal-db + mountPath: /var/lib/postgresql/data + env: + - name: POSTGRES_DB + value: database + - name: PGDATA + value: /var/lib/postgresql/data/pgdata/subdir + - name: POSTGRES_USER + value: adventure + - name: POSTGRES_PASSWORD + valueFrom: + secretKeyRef: + name: adventurelog-secret + key: adventure-postgres-password + + - name: adventure-backend + image: ghcr.io/seanmorley15/adventurelog-backend:latest + imagePullPolicy: IfNotPresent + ports: + - containerPort: 80 + - containerPort: 8000 + volumeMounts: + - name: adventure-journal + mountPath: /code/media + env: + - name: PGHOST + value: "adventure-db-svc" + - name: PGDATABASE + value: "database" + - name: PGUSER + value: "adventure" + - name: PGPASSWORD + valueFrom: + secretKeyRef: + name: adventurelog-secret + key: adventure-postgres-password + - name: SECRET_KEY + valueFrom: + secretKeyRef: + name: adventurelog-secret + key: adventure-postgres-password + - name: PUBLIC_URL + value: "http://internally-and-externally.reachable.io:80" # Match the outward port, used for the creation of image urls + - name: FRONTEND_URL + value: "http://url-typed-into-browser.io:80" + - name: CSRF_TRUSTED_ORIGINS + value: "http://url-typed-into-browser.io:80, http://internally-and-externally.reachable.io:80" + - name: DJANGO_ADMIN_USERNAME + value: "admin" + - name: DJANGO_ADMIN_PASSWORD + value: "admin" + - name: DJANGO_ADMIN_EMAIL + value: "admin@example.com" + - name: DEBUG + value: "True" + restartPolicy: Always +--- +apiVersion: v1 +kind: Service +metadata: + name: adventure-db-svc +spec: + selector: + app: adventure + ports: + - name: db + protocol: TCP + port: 5432 + targetPort: 5432 +--- +apiVersion: v1 +kind: Service +metadata: + name: server +spec: + selector: + app: adventure + ports: + - name: http + protocol: TCP + port: 80 + targetPort: 80 + - name: base + protocol: TCP + port: 8000 + targetPort: 8000 +--- +# If you aren't automatically provisioning PVCs (i.e. with Longhorn, you'll need to also create the PV's) +apiVersion: v1 +kind: PersistentVolumeClaim +metadata: + name: adventure-journal-pvc +spec: + accessModes: + - ReadWriteOnce + resources: + requests: + storage: 10Gi +--- +apiVersion: v1 +kind: PersistentVolumeClaim +metadata: + name: adventure-journal-db-pvc +spec: + accessModes: + - ReadWriteOnce + resources: + requests: + storage: 10Gi +``` \ No newline at end of file From 91a51515dd01b7fde09302dbc97c5c5eec82a853 Mon Sep 17 00:00:00 2001 From: MaximUltimatum Date: Sat, 7 Dec 2024 14:31:13 -0500 Subject: [PATCH 2/3] Removing extraneous env variable info that is externally linked --- documentation/docs/install/kustomize.md | 26 +------------------------ 1 file changed, 1 insertion(+), 25 deletions(-) diff --git a/documentation/docs/install/kustomize.md b/documentation/docs/install/kustomize.md index 3f972be6..6575325b 100644 --- a/documentation/docs/install/kustomize.md +++ b/documentation/docs/install/kustomize.md @@ -16,7 +16,7 @@ Once you have made said ingress, set `PUBLIC_SERVER_URL` and `PUBLIC_URL` env va ## Tailscale and Headscale Many k8s homelabs choose to use [Tailscale](https://tailscale.com/) or similar projects to remove the need for open ports in your home firewall. -The [Tailscale k8s Operator](https://tailscale.com/kb/1185/kubernetes/) will set up an externally resolvable service/ingress for your AdventureLog instance +The [Tailscale k8s Operator](https://tailscale.com/kb/1185/kubernetes/) will set up an externally resolvable service/ingress for your AdventureLog instance, but it will fail to resolve internally. You must [expose tailnet IPs to your cluster](https://tailscale.com/kb/1438/kubernetes-operator-cluster-egress#expose-a-tailnet-https-service-to-your-cluster-workloads) so the AdventureLog pods can resolve them. @@ -29,28 +29,4 @@ Take a look at the [example config](kustomize_example.md) and modify it for your Look at the [environment variable summary](docker.md#configuration) in the docker install section to see available and required configuration options. -### Frontend Container (web) - -| Name | Required | Description | Default Value | -| ------------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------- | -| `PUBLIC_SERVER_URL` | Yes | What the frontend SSR server uses to connect to the backend. | http://server:8000 | -| `ORIGIN` | Sometimes | Not needed if using HTTPS. If not, set it to the domain of what you will acess the app from. | http://localhost:8015 | -| `BODY_SIZE_LIMIT` | Yes | Used to set the maximum upload size to the server. Should be changed to prevent someone from uploading too much! Custom values must be set in **kiliobytes**. | Infinity | - -### Backend Container (server) - -| Name | Required | Description | Default Value | -| ----------------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------- | -| `PGHOST` | Yes | Databse host. | db | -| `PGDATABASE` | Yes | Database. | database | -| `PGUSER` | Yes | Database user. | adventure | -| `PGPASSWORD` | Yes | Database password. | changeme123 | -| `DJANGO_ADMIN_USERNAME` | Yes | Default username. | admin | -| `DJANGO_ADMIN_PASSWORD` | Yes | Default password, change after inital login. | admin | -| `DJANGO_ADMIN_EMAIL` | Yes | Default user's email. | admin@example.com | -| `PUBLIC_URL` | Yes | This needs to match the outward port of the server and be accessible from where the app is used. It is used for the creation of image urls. | 'http://localhost:8016' | -| `CSRF_TRUSTED_ORIGINS` | Yes | Need to be changed to the orgins where you use your backend server and frontend. These values are comma seperated. | http://localhost:8016 | -| `FRONTEND_URL` | Yes | This is the publically accessible url to the **frontend** container. This link should be accessable for all users. Used for email generation. | 'http://localhost:8015' | - - Enjoy AdventureLog! 🎉 From 914028ea2fadbec2e031e04176c080360e2dcfe3 Mon Sep 17 00:00:00 2001 From: Sean Morley Date: Sat, 7 Dec 2024 16:25:31 -0500 Subject: [PATCH 3/3] Update Kubernetes and Kustomize documentation --- documentation/.vitepress/config.mts | 4 ++++ documentation/docs/install/kustomize.md | 6 ++++-- .../install/kustomize_example.md => kustomization.yml | 10 ++++------ 3 files changed, 12 insertions(+), 8 deletions(-) rename documentation/docs/install/kustomize_example.md => kustomization.yml (97%) diff --git a/documentation/.vitepress/config.mts b/documentation/.vitepress/config.mts index 5e315f8e..243cec99 100644 --- a/documentation/.vitepress/config.mts +++ b/documentation/.vitepress/config.mts @@ -65,6 +65,10 @@ export default defineConfig({ { text: "Docker 🐋", link: "/docs/install/docker" }, { text: "Proxmox LXC 🐧", link: "/docs/install/proxmox_lxc" }, { text: "Synology NAS ☁️", link: "/docs/install/synology_nas" }, + { + text: "Kubernetes and Kustomize 🌐", + link: "/docs/install/kustomize", + }, { text: "With A Reverse Proxy", diff --git a/documentation/docs/install/kustomize.md b/documentation/docs/install/kustomize.md index 6575325b..5e9d0744 100644 --- a/documentation/docs/install/kustomize.md +++ b/documentation/docs/install/kustomize.md @@ -1,4 +1,4 @@ -# Kustomize (k8s) +# Kubernetes and Kustomize (k8s) _AdventureLog can be run inside a kubernetes cluster using [kustomize](https://kustomize.io/)._ @@ -7,6 +7,7 @@ _AdventureLog can be run inside a kubernetes cluster using [kustomize](https://k A working kubernetes cluster. AdventureLog has been tested on k8s, but any Kustomize-capable flavor should be easy to use. ## Cluster Routing + Because the AdventureLog backend must be reachable by **both** the web browser and the AdventureLog frontend, k8s-internal routing mechanisms traditional for standing up other similar applications **cannot** be used. In order to host AdventureLog in your cluster, you must therefor configure an internally and externally resolvable ingress that routes to your AdventureLog backend container. @@ -14,6 +15,7 @@ In order to host AdventureLog in your cluster, you must therefor configure an in Once you have made said ingress, set `PUBLIC_SERVER_URL` and `PUBLIC_URL` env variables below to the url of that ingress. ## Tailscale and Headscale + Many k8s homelabs choose to use [Tailscale](https://tailscale.com/) or similar projects to remove the need for open ports in your home firewall. The [Tailscale k8s Operator](https://tailscale.com/kb/1185/kubernetes/) will set up an externally resolvable service/ingress for your AdventureLog instance, @@ -23,7 +25,7 @@ You must [expose tailnet IPs to your cluster](https://tailscale.com/kb/1438/kube ## Getting Started -Take a look at the [example config](kustomize_example.md) and modify it for your usecase. +Take a look at the [example config](https://github.com/seanmorley15/AdventureLog/blob/main/kustomization.yml) and modify it for your usecase. ## Environment Variables diff --git a/documentation/docs/install/kustomize_example.md b/kustomization.yml similarity index 97% rename from documentation/docs/install/kustomize_example.md rename to kustomization.yml index 9396c326..da7c6e77 100644 --- a/documentation/docs/install/kustomize_example.md +++ b/kustomization.yml @@ -1,4 +1,3 @@ -```yaml apiVersion: apps/v1 kind: Deployment metadata: @@ -36,7 +35,7 @@ spec: value: "http://url-typed-into-browser.io:80" - name: BODY_SIZE_LIMIT value: "Infinity" - + - name: adventure-db image: postgis/postgis:15-3.3 imagePullPolicy: IfNotPresent @@ -53,7 +52,7 @@ spec: - name: POSTGRES_USER value: adventure - name: POSTGRES_PASSWORD - valueFrom: + valueFrom: secretKeyRef: name: adventurelog-secret key: adventure-postgres-password @@ -75,7 +74,7 @@ spec: - name: PGUSER value: "adventure" - name: PGPASSWORD - valueFrom: + valueFrom: secretKeyRef: name: adventurelog-secret key: adventure-postgres-password @@ -125,7 +124,7 @@ spec: protocol: TCP port: 80 targetPort: 80 - - name: base + - name: base protocol: TCP port: 8000 targetPort: 8000 @@ -152,4 +151,3 @@ spec: resources: requests: storage: 10Gi -``` \ No newline at end of file