diff --git a/documentation/docs/install/kustomize.md b/documentation/docs/install/kustomize.md new file mode 100644 index 0000000..3f972be --- /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 0000000..9396c32 --- /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