docs: initial CI setup

.github/workflows/docs.yml

@@ -0,0 +1,41 @@
+name: Deploy pages
+on:
+  push:
+    branches:
+      - main
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: "0"
+          fetch-tags: "true"
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.13"
+
+      - run: echo "cache_id=$(date --utc '+%V')" >> $GITHUB_ENV
+
+      - uses: actions/cache@v4
+        with:
+          key: mkdocs-material-${{ env.cache_id }}
+          path: .cache
+          restore-keys: |
+            mkdocs-material-
+
+      - name: Install python packages
+        run: pip install -r requirements.txt
+
+      - name: Build the website
+        run: mkdocs build
+
+      - name: Copy files to the s3 website content bucket
+        run: aws s3 sync site s3://${{ secrets.HCLOUD_BUCKET }} --delete
+        env:
+          AWS_ACCESS_KEY_ID: ${{ secrets.HCLOUD_KEY_ID }}
+          AWS_SECRET_ACCESS_KEY: ${{ secrets.HCLOUD_SECRET_KEY }}
+          AWS_DEFAULT_REGION: hel1
+          AWS_ENDPOINT_URL: ${{ secrets.HCLOUD_ENDPOINT }}

.gitignore

@@ -2,5 +2,5 @@ bin/
 out/
 .idea/
 .venv/
-# Added by goreleaser init:
+site/
 dist/

README.md

@@ -1,16 +1,46 @@
 # supabase-operator
-// TODO(user): Add simple overview of use/purpose
+
+This is a Kubernetes operator for managing Supabase instances.
+It is built using the [Kubebuilder](https://book.kubebuilder.io/) framework.
 
 ## Description
-// TODO(user): An in-depth paragraph about your project and overview of use
+
+This is currently a work-in-progress experiment to replace existing Helm charts for Supabase as they tend to be hard to deploy and to manage and the default Supabase stack - although working great as a single instance or in their SaaS instances - isn't a perfect fit for Kubernetes.
+This operator replaces tedious Helm values files with a small set of custom resources that allow an user to quickly deploy a Supabase instance without having to know much (if anything) of the Supabase internals.
+
+## Targets
+
+- Make it as easy as possible to deploy Supabase on a Kubernetes cluster
+- Manage updates of components
+- Run Supabase specific migrations on the database (those managed in the supabase/postgres repository)
+- Make Supabase as resource effective as possible (e.g. replaced Kong with Envoy)
+- Keep it as secure as possible (e.g. adding OAuth2/Basic auth to studio if desired)
+- Manage **all** aspects of the Kubernetes resources, this operator manages everything where a user would need deeper insights into Supabase like:
+  - Deployments
+  - Services
+  - Secrets (although you can ship your own if you want to)
+  - ConfigMaps
+  - *soon*: NetworkPolicies
+
+## Non-Targets
+
+- Manage **all** Kubernetes aspects, it does **not** create:
+  - PodDisruptionBudgets
+  - HorizontalPodAutoscalers
+  - Ingress or HTTPRoutes
+- Replace existing Postgres operators like cloudnative-pg, CrunchyData, Zalando Postgres Operator, ...
+- Manage the database instance e.g. making backups, ... that should be done by the Postgres operator or by the user
+- Manage your application e.g. run app specific migrations, host your frontend, ...
+
+This operator tries to be as un-opionionated as possible and thereofore does not make assumptions on how you expose APIs to your users (Ingress, GatewayAPI, LoadBalancer service (coming soon))...
 
 ## Getting Started
 
 ### Prerequisites
-- go version v1.22.0+
-- docker version 17.03+.
-- kubectl version v1.11.3+.
-- Access to a Kubernetes v1.11.3+ cluster.
+- go version v1.23.x+
+- docker version 27.+.
+- kubectl version v1.30.0+.
+- Access to a Kubernetes v1.30.+ cluster.
 
 ### To Deploy on the cluster
 **Build and push your image to the location specified by `IMG`:**
@@ -89,16 +119,9 @@ Users can just run kubectl apply -f <URL for YAML BUNDLE> to install the project
 kubectl apply -f https://raw.githubusercontent.com/<org>/supabase-operator/<tag or branch>/dist/install.yaml
 ```
 
-## Contributing
-// TODO(user): Add detailed information on how you would like others to contribute to this project
-
-**NOTE:** Run `make help` for more information on all potential `make` targets
-
-More information can be found via the [Kubebuilder Documentation](https://book.kubebuilder.io/introduction.html)
-
 ## License
 
-Copyright 2024 Peter Kurfer.
+Copyright 2025 Peter Kurfer.
 
 Licensed under the Apache License, Version 2.0 (the "License");
 you may not use this file except in compliance with the License.
@@ -111,4 +134,3 @@ distributed under the License is distributed on an "AS IS" BASIS,
 WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 See the License for the specific language governing permissions and
 limitations under the License.
-

docs/components/overview.md

@@ -0,0 +1,19 @@
+# Overview
+
+## Architecture
+
+The following diagram explains the overall architecture of Supabase as it is deployed from this operator:
+
+```kroki-excalidraw
+@from_file:./images/overview.excalidraw
+```
+
+The dashed parts on the left are not managed by this operator but illustrate how traffic can be routed to the Supabase instance.
+
+## Core
+
+The `Core` custom resource (CR) is the basic resource that - if not in an 'edge case' (pun intended) - configures all basic aspects of a Supabase instance:
+
+- PostgREST API
+- Supabase Auth
+- initial database migrations

docs/getting_started.md

@@ -0,0 +1,14 @@
+# Getting Started
+
+## Deploying the operator
+
+The easiest way to deploy the operator is to fetch the manifest from the [releases](https://code.icb4dc0.de/prskr/supabase-operator/releases) and apply it like this:
+
+```bash
+kubectl apply --server-side -f manifest.yaml
+```
+
+The manifest is rendered as part of the release workflow and based on [kustomize](https://kustomize.io/).
+If you want to customize the deployment, you can start from the [release/default](https://code.icb4dc0.de/prskr/supabase-operator/src/branch/main/config/release/default) layer and build your own manifest.
+
+## Deploying a basic Supabase instance

docs/index.md

@@ -1,17 +1,36 @@
-# Welcome to MkDocs
+# About
 
-For full documentation visit [mkdocs.org](https://www.mkdocs.org).
+This is a Kubernetes operator for managing self-hosted [Supabase](https://supabase.com/) instances.
+It is built using the [Kubebuilder](https://book.kubebuilder.io/) framework.
+This project is not affiliated with the Supabase project or company in any way.
 
-## Commands
+## Description
 
-* `mkdocs new [dir-name]` - Create a new project.
-* `mkdocs serve` - Start the live-reloading docs server.
-* `mkdocs build` - Build the documentation site.
-* `mkdocs -h` - Print help message and exit.
+This is currently a work-in-progress experiment to replace existing Helm charts for Supabase as they tend to be hard to deploy and to manage and the default Supabase stack - although working great as a single instance or in their SaaS instances - isn't a perfect fit for Kubernetes.
+This operator replaces tedious Helm values files with a small set of custom resources that allow an user to quickly deploy a Supabase instance without having to know much (if anything) of the Supabase internals.
 
-## Project layout
+## Targets
 
-    mkdocs.yml    # The configuration file.
-    docs/
-        index.md  # The documentation homepage.
-        ...       # Other markdown pages, images and other files.
+- Make it as easy as possible to deploy Supabase on a Kubernetes cluster
+- Manage updates of components
+- Run Supabase specific migrations on the database (those managed in the supabase/postgres repository)
+- Make Supabase as resource effective as possible (e.g. replaced Kong with Envoy)
+- Keep it as secure as possible (e.g. adding OAuth2/Basic auth to studio if desired)
+- Manage **all** aspects of the Kubernetes resources, this operator manages everything where a user would need deeper insights into Supabase like:
+  - Deployments
+  - Services
+  - Secrets (although you can ship your own if you want to)
+  - ConfigMaps
+  - *soon*: NetworkPolicies
+
+## Non-Targets
+
+- Manage **all** Kubernetes aspects, it does **not** create:
+  - PodDisruptionBudgets
+  - HorizontalPodAutoscalers
+  - Ingress or HTTPRoutes
+- Replace existing Postgres operators like cloudnative-pg, CrunchyData, Zalando Postgres Operator, ...
+- Manage the database instance e.g. making backups, ... that should be done by the Postgres operator or by the user
+- Manage your application e.g. run app specific migrations, host your frontend, ...
+
+This operator tries to be as un-opionionated as possible and thereofore does not make assumptions on how you expose APIs to your users (Ingress, GatewayAPI, LoadBalancer service (coming soon))...

mkdocs.yml

@@ -9,18 +9,16 @@ theme:
     - search.highlight
     - toc.integrate
 
-markdown_extensions:
-  - pymdownx.superfences:
-      custom_fences:
-        - name: mermaid
-          class: mermaid
-          format: !!python/name:pymdownx.superfences.fence_code_format
-
 plugins:
   - search
+  - kroki:
+      HttpMethod: POST
 
 nav:
   - Home:
       - About: index.md
       - Getting Started: getting_started.md
+  - Components:
+      - Overview: components/overview.md
+      - Core: components/core.md
   - API Reference: api/supabase.k8s.icb4dc0.de.md

requirements.txt

@@ -1,2 +1,2 @@
-Pygments
 mkdocs-material
+mkdocs-kroki-plugin