{"id":19482531,"url":"https://github.com/git-ogawa/docserver-controller","last_synced_at":"2026-05-15T20:05:39.042Z","repository":{"id":176531083,"uuid":"656200277","full_name":"git-ogawa/docserver-controller","owner":"git-ogawa","description":"Kubernetes custom controller with kubebuilder.","archived":false,"fork":false,"pushed_at":"2023-06-27T15:52:02.000Z","size":238,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-07-25T07:48:14.119Z","etag":null,"topics":["kubebuilder","kubernetes"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/git-ogawa.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2023-06-20T13:02:16.000Z","updated_at":"2023-06-27T15:53:47.000Z","dependencies_parsed_at":null,"dependency_job_id":"f2015f48-ae30-48df-9bc5-e43836892418","html_url":"https://github.com/git-ogawa/docserver-controller","commit_stats":null,"previous_names":["git-ogawa/docserver-controller"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/git-ogawa/docserver-controller","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/git-ogawa%2Fdocserver-controller","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/git-ogawa%2Fdocserver-controller/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/git-ogawa%2Fdocserver-controller/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/git-ogawa%2Fdocserver-controller/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/git-ogawa","download_url":"https://codeload.github.com/git-ogawa/docserver-controller/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/git-ogawa%2Fdocserver-controller/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33078039,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-15T11:35:32.926Z","status":"ssl_error","status_checked_at":"2026-05-15T11:35:31.362Z","response_time":103,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["kubebuilder","kubernetes"],"created_at":"2024-11-10T20:10:57.633Z","updated_at":"2026-05-15T20:05:39.004Z","avatar_url":"https://github.com/git-ogawa.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Docserver-controller\n\nDocserver-controller is a kubernetes custom controller to manage the CRD called docserver. This project is for users to deploy docserver-controller into your cluster.\n\nThe project has been developed with kubebuilder.\n\n\n# Table of Contents\n\n- [Description](#description)\n- [Install](#install)\n- [Usage](#usage)\n  - [Prerequisites](#prerequisites)\n  - [Deploying](#deploying)\n- [Options](#options)\n  - [Authentication](#authentication)\n    - [Basic Authentication](#basic-authentication)\n    - [Private repository using self-signed certificates.](#private-repository-using-self-signed-certificates)\n    - [SSH private key](#ssh-private-key)\n  - [Using custom image](#using-custom-image)\n  - [PersistentVolumeClaim options](#persistentvolumeclaim-options)\n- [Develop](#develop)\n  - [Running on the cluster](#running-on-the-cluster)\n  - [Uninstall CRDs](#uninstall-crds)\n  - [Undeploy controller](#undeploy-controller)\n\n\n# Description\n\nIn the project, the word \"docserver\" means a pod where [mkdocs](https://www.mkdocs.org/) is running. Docserver-controller manages the status of the Custom Resource Definitions (CRD) including docserver definition.\n\nWhen users deploy CRD into the cluster, the following components are created and managed by the controller.\n\n- `Gitpod` : A pod owned by Job. The main job is to pull the source of the documents from external git repository (github, gitlab or others) and store them into PersistentVolume.\n- `Docserver` : A set of pods where mkdocs is running. The pods share the source of the documents in PersistentVolume.\n- `PersistentVolumeClaim` : PersistentVolumeClaim used to store the source of the document that is shared by gitpod and docserver. This will be bound to a PersistentVolume created by user or dynamic provisioner.\n- `Service` : A endpoint for user access to docserver.\n\n\nThe figure below shows the relations between the components.\n\n![](docs/docserver.png)\n\n\n# Install\n\nYou can install the docserver-controller with helm. The cert-manager have to be installed in your cluster before installing the project. See [Installation](https://cert-manager.io/docs/installation/) on the documentation to install the cert-manager.\n\nThen clone this repository, move to project directory and run `helm install` to install the project from the local chart.\n\n```\nhelm install docserver --namespace docserver ./charts/docserver/ --create-namespace\n```\n\n\n# Usage\n\n## Prerequisites\n\nA git repository that stores the source of the documents is required. The source will be built and published by mkdocs on the docserver pods.\n\nThe repository have to meet the followings.\n\n- The mkdocs configuration (`mkdocs.yml`) is in the project top directory.\n- The source are under in docs in the project top directory\n\nThe typical directory tree will be the following.\n\n```\n(project root)\n├── mkdocs.yml\n├── docs\n│   ├── index.md\n│   └── ...\n└── (others)\n```\n\nThe PersistentVolume also have to be created in the cluster so that PersistentVolumeClaim will be bound to it. This step can be skipped if PersistentVolume will be bound with dynamic provisioning.\n\nYou have to set the properties of PersistentVolume to meet the followings.\n\n- `accessModes` : Set `ReadWriteMany`.\n- `capacity.storage` : Equal or greater than `3Gi`.\n- `storageClassName` : Set `default`.\n\n``` yaml\n# Example\nkind: PersistentVolume\napiVersion: v1\nmetadata:\n  name: mypv\nspec:\n  storageClassName: default\n  capacity:\n    storage: 10Gi\n  accessModes:\n  - ReadWriteMany\n  hostPath:\n    path: /data\n```\n\n## Deploying\n\nTo deploy docserver CRD in your cluster, create a CRD manifest. The following fields have to be set at least.\n\n- apiVersion : Set `update.git-ogawa.github.io/v1beta1`.\n- kind : Set `DocServer`.\n- spec\n    - target\n        - url : URL of the git repository where the source of the documents will be pulled.\n        - branch : Branch of the repository to be pulled. `main` by default.\n    - replicas : The replica number of docserver pod.\n\nHere is the example manifest in `config/samples/update_v1beta1_docserver.yaml`.\n\n``` yaml\n---\napiVersion: update.git-ogawa.github.io/v1beta1\nkind: DocServer\nmetadata:\n  name: sample\nspec:\n  target:\n    url: https://github.com/git-ogawa/mkdocs-example.git\n    branch: main\n  replicas: 3\n```\n\nRun `kubectl apply -f config/samples/update_v1beta1_docserver.yaml` to deploy. The status of gitpod pod will be `Completed` and the docserver pods, persistentVolumeClaim and services are created.\n\n```\n$ kubectl get pod,svc,pvc\nNAME                                                READY   STATUS      RESTARTS   AGE\npod/docserver-controller-manager-7c84b84c68-wxf69   2/2     Running     0          59m\npod/docserver-sample-78bc8559cf-k5xt7               1/1     Running     0          83s\npod/docserver-sample-78bc8559cf-knw9h               1/1     Running     0          83s\npod/docserver-sample-78bc8559cf-nh4kx               1/1     Running     0          83s\npod/gitpod-sample-dl587                             0/1     Completed   0          83s\n\nNAME                                                   TYPE        CLUSTER-IP       EXTERNAL-IP   PORT(S)    AGE\nservice/docserver-controller-manager-metrics-service   ClusterIP   10.109.15.25     \u003cnone\u003e        8443/TCP   59m\nservice/docserver-sample                               ClusterIP   10.102.119.207   \u003cnone\u003e        8000/TCP   83s\nservice/docserver-webhook-service                      ClusterIP   10.110.230.81    \u003cnone\u003e        443/TCP    59m\n\nNAME                                     STATUS   VOLUME   CAPACITY   ACCESS MODES   STORAGECLASS   AGE\npersistentvolumeclaim/docserver-sample   Bound    mypv     3Gi        RWX            default        60s\n```\n\nYou can access docserver pods through service port 8000.\n\n```\n$ kubectl port-forward svc/docserver-example 8000:8000\nForwarding from 127.0.0.1:8000 -\u003e 8000\nForwarding from [::1]:8000 -\u003e 8000\n\n# Check if the server is running in another console\n$ curl 0.0.0.0:8000 -I\nHTTP/1.0 200 OK\nDate: Wed, 21 Jun 2023 12:44:40 GMT\nServer: WSGIServer/0.2 CPython/3.11.4\nContent-Type: text/html\nContent-Length: 9345\n```\n\n# Options\n\n## Authentication\n\nWhen user pull the source from repositories that authentication is required, additional options must be set in the manifest. DocServer CRD provides some options about the authentication.\n\n\n### Basic Authentication\n\nIf basic authentication is required when access to repositories, at first user have to create a secret including username and password.\n\n``` yaml\napiVersion: v1\nkind: Secret\nmetadata:\n  name: [your_secretname]\ntype: kubernetes.io/basic-auth\nstringData:\n  username: [your_username]\n  password: [your_password]\n```\n\nOnce the secret is created, make CRD manifest that set the name of the secret in `.spec.target.basicAuthSecret`.\n\n\n``` yaml\nspec:\n  target:\n    ...\n    basicAuthSecret: [your_secret_name]\n```\n\n\n### Private repository using self-signed certificates.\n\n\nIf the source of the documents is managed in the repository using self-signed certificates or custom certificates authority, the docserver provides two options.\n\n\nThe first is to set `.spec.target.sslVerify: false` not to check server identity.\n\n``` yaml\nspec:\n  target:\n    ...\n    sslVerify: false\n```\n\nThe second is to configure manifest to trust your certificate. Save the CA certificate used by the repository as `ca.crt` and create kubernetes secret by the following commands.\n\n```\nkubectl create secret generic [secret_name] --from-file=ca.crt\n```\n\nThen set the secret to `spec.target.tlsSecret`.\n\n``` yaml\nspec:\n  target:\n    ...\n    tlsSecret: [secret_name]\n```\n\n### SSH private key\n\nIf you want to pull the source with ssh protocol, you need to prepare ssh configuration.\n\nTo use ssh protocol when pulling the source, create configmap to set configuration used ssh clone.\n\n``` yaml\napiVersion: v1\nkind: ConfigMap\nmetadata:\n  name: [your_config_name]\ndata:\n  config: |\n    Host my.git.server\n      HostName 192.168.3.2\n      User git\n      Port 22\n      IdentityFile ~/.ssh/id_rsa\n```\n\nThe content above corresponds to the following `~/.ssh/config`.\n\n```\nHost my.git.server\n  HostName 192.168.3.2\n  User git\n  Port 22\n  IdentityFile ~/.ssh/id_rsa\n```\n\nThen create kubernetes secret to store ssh private-key. Replace key filename if you use other ssh key type.\n\n```\nkubectl create secret generic [your_secret_name] --from-file=id.rsa\n```\n\nFinally, set the configmap and secret to `sepc.target.sshSecret.config` and `sepc.target.sshSecret.config`.\n\n``` yaml\nspec:\n  target:\n    ...\n    sshSecret:\n      config: [your_config_name]\n      privatekey: [your_secret_name]\n```\n\n\n## Using custom image\n\nThe image used by docserver pod by default is [squidfunk/mkdocs-material](https://hub.docker.com/r/squidfunk/mkdocs-material). If you want to use other image, you can build your own image and use it. The image have to meet the following condition.\n\n- WORKDIR is `/docs`.\n- ENTRYPOINT is `mkdocs`.\n- The arguments of CMD include `serve`.\n\nThe example Dockerfile that install additional plantuml package is the following.\n\n``` Dockerfile\nFrom python:3.11-slim-bookworm\n\nRUN pip install --no-cache-dir \\\n    mkdocs \\\n    mkdocs-material \\\n    plantuml-markdown\n\nRUN mkdir /docs\nWORKDIR /docs\n\nENTRYPOINT [\"mkdocs\"]\nCMD [\"serve\", \"--dev-addr=0.0.0.0:8000\"]\n```\n\nOnce build your image, you can use it as docserver image by setting the name to `.spec.image` in a manifest.\n\n``` yaml\nspec:\n  ...\n  image: [your_image]\n```\n\n\n## PersistentVolumeClaim options\n\nDocserver controller creates PersistentVolumeClaim to store the sources of the document when docserver CRD is created in the cluster. The request size is `3Gi` and storageClassName is `default` by default. You can change the size and storageClassName by settings the values in a manifest.\nYOu have to set correct storageClass supported by provisioner if you want to use dynamic volume provisioning.\n\n``` yaml\nspec:\n  ...\n  storage:\n    size: 5Gi\n    storageClass: myclass\n```\n\n\n# Develop\n\nThis section is for developer.\n\n\nYou’ll need a Kubernetes cluster to run against. You can use [KIND](https://sigs.k8s.io/kind) to get a local cluster for testing, or run against a remote cluster.\n**Note:** Your controller will automatically use the current context in your kubeconfig file (i.e. whatever cluster `kubectl cluster-info` shows).\n\n## Running on the cluster\n1. Install Instances of Custom Resources:\n\n```sh\nkubectl apply -f config/samples/\n```\n\n2. Build and push your image to the location specified by `IMG`:\n\n```sh\nmake docker-build docker-push IMG=\u003csome-registry\u003e/docserver:tag\n```\n\n3. Deploy the controller to the cluster with the image specified by `IMG`:\n\n```sh\nmake deploy IMG=\u003csome-registry\u003e/docserver:tag\n```\n\n## Uninstall CRDs\nTo delete the CRDs from the cluster:\n\n```sh\nmake uninstall\n```\n\n## Undeploy controller\nUnDeploy the controller from the cluster:\n\n```sh\nmake undeploy\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgit-ogawa%2Fdocserver-controller","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgit-ogawa%2Fdocserver-controller","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgit-ogawa%2Fdocserver-controller/lists"}