{"id":13674365,"url":"https://github.com/docat-org/docat","last_synced_at":"2026-01-23T02:11:48.930Z","repository":{"id":37147374,"uuid":"220474250","full_name":"docat-org/docat","owner":"docat-org","description":"Host your docs. Simple. Versioned. Fancy.","archived":false,"fork":false,"pushed_at":"2025-06-24T13:20:35.000Z","size":4966,"stargazers_count":880,"open_issues_count":14,"forks_count":51,"subscribers_count":9,"default_branch":"main","last_synced_at":"2026-01-20T18:37:14.708Z","etag":null,"topics":["docs","fancy","hacktoberfest","hosting","selfhosted","versioning"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/docat-org.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","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,"zenodo":null}},"created_at":"2019-11-08T13:38:54.000Z","updated_at":"2026-01-19T15:03:29.000Z","dependencies_parsed_at":"2023-10-02T12:37:27.266Z","dependency_job_id":"aab2fffd-30c7-4d2f-a3b2-69855f7c7b1d","html_url":"https://github.com/docat-org/docat","commit_stats":null,"previous_names":[],"tags_count":31,"template":false,"template_full_name":null,"purl":"pkg:github/docat-org/docat","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/docat-org%2Fdocat","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/docat-org%2Fdocat/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/docat-org%2Fdocat/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/docat-org%2Fdocat/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/docat-org","download_url":"https://codeload.github.com/docat-org/docat/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/docat-org%2Fdocat/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28677718,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-23T01:00:35.747Z","status":"online","status_checked_at":"2026-01-23T02:00:08.296Z","response_time":59,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"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":["docs","fancy","hacktoberfest","hosting","selfhosted","versioning"],"created_at":"2024-08-02T11:00:47.989Z","updated_at":"2026-01-23T02:11:48.924Z","avatar_url":"https://github.com/docat-org.png","language":"TypeScript","funding_links":[],"categories":["TypeScript","Software","hacktoberfest"],"sub_categories":["Document Management","Miscellaneous"],"readme":"![docat](doc/assets/docat-teaser.png)\n\n**Host your docs. Simple. Versioned. Fancy.**\n\n[![build](https://github.com/docat-org/docat/workflows/docat%20ci/badge.svg)](https://github.com/docat-org/docat/actions)\n[![Gitter](https://badges.gitter.im/docat-docs-hosting/community.svg)](https://gitter.im/docat-docs-hosting/community?utm_source=badge\u0026utm_medium=badge\u0026utm_campaign=pr-badge)\n\n## Why DOCAT?\n\nWhen generating static documentation using\n[mkdocs](https://www.mkdocs.org/), [sphinx](http://www.sphinx-doc.org/en/master/), ...\nhosting just one version of the docs might not be enough.\nMany users might still use older versions and might need to read\nthose versions of the documentation.\n\nDocat solves this problem by providing a simple tool that\nhosts multiple documentation projects with multiple versions.\n\n*The main design decision with docat was to keep the tool as simple as possible.*\n\n## Getting started\n\nThe simplest way to get started is to run the docker container,\nyou can optionally use volumes to persist state:\n\n```sh\n# run container in background and persist data (docs, nginx configs and tokens database)\n# use 'ghcr.io/docat-org/docat:unstable' to get the latest changes\nmkdir -p docat-run/doc\ndocker run \\\n  --detach \\\n  --volume $PWD/docat-run:/var/docat/ \\\n  --publish 8000:80 \\\n  ghcr.io/docat-org/docat\n```\n\nGo to [localhost:8000](http://localhost:8000) to view your docat instance:\n\n\u003cimg src=\"doc/assets/docat.gif\" width=\"100%\" /\u003e\n\n### Using DOCAT\n\n\u003e 🛈 Please note that docat does not provide any way to write documentation.\n\u003e It's sole responsibility is to host documentation.\n\u003e\n\u003e There are many awesome tools to write documenation:\n\u003e - [mkdocs](https://www.mkdocs.org/)\n\u003e - [sphinx](http://www.sphinx-doc.org/en/master/)\n\u003e - [mdbook](https://rust-lang.github.io/mdBook/)\n\u003e - ...\n\n\nA CLI tool called [docatl](https://github.com/docat-org/docatl) is available\nfor easy interaction with the docat server.\nHowever, interacting with docat can also be done through [`curl`](doc/getting-started.md).\n\nTo push documentation (and tag as `latest`) in the folder `docs/` simply run:\n\n```sh\ndocatl push --host http://localhost:8000 ./docs PROJECT VERSION --tag latest\n```\n\nMore detailed instructions can be found in the [**getting started guide**](doc/getting-started.md).\n\n## Authentication\n\nBy default, anyone can upload new documentation or add a new version to documentation.\nA project can be claimed. A claim returns a token that then must be used\nto add or delete versions.\n\nWhen hosting docat publicly, it is recommended to use\n[http basic auth](https://docs.nginx.com/nginx/admin-guide/security-controls/configuring-http-basic-authentication/)\nfor all `POST`/`PUT` and `DELETE` http calls.\n\n\u003cdetails\u003e\n  \u003csummary\u003edocat http basic authentication example\u003c/summary\u003e\n\nThis example shows how to configure the NGINX inside the docker image\nto be password protected using http basic auth.\n\n1) Create your [`.htpasswd` file](https://docs.nginx.com/nginx/admin-guide/security-controls/configuring-http-basic-authentication/#creating-a-password-file).\n2) And a custom `default` NGINX config:\n\n  ```\n  upstream python_backend {\n      server 127.0.0.1:5000;\n  }\n\n  server {\n      listen 80 default_server;\n      listen [::]:80 default_server;\n\n      root /var/www/html;\n\n      add_header Content-Security-Policy \"frame-ancestors 'self';\";\n      index index.html index.htm index.pdf /index.html;\n\n      server_name _;\n\n      location /doc {\n          root /var/docat;\n      }\n\n      location /api {\n          limit_except GET HEAD {\n              auth_basic 'Restricted';\n              auth_basic_user_file /etc/nginx/.htpasswd;\n          }\n\n          client_max_body_size $MAX_UPLOAD_SIZE;\n          proxy_pass http://python_backend;\n      }\n\n      location / {\n          try_files $uri $uri/ =404;\n      }\n  }\n  ```\n\n1) Mounted to the correct location inside the container:\n\n  ```\n  docker run \\\n    --detach \\\n    --volume $PWD/docat-run:/var/docat/ \\\n    --volume $PWD/nginx/default:/app/docat/docat/nginx/default \\\n    --volume $PWD/nginx/.htpasswd:/etc/nginx/.htpasswd \\\n    --publish 8000:80 \\\n    ghcr.io/docat-org/docat\n  ```\n\u003c/details\u003e\n\n## Configuring DOCAT\n\n#### Frontend Config\n\nIt is possible to configure some things after the fact.\n\n1. Create a `config.json` file\n2. Mount it inside your docker container `--volume $PWD/config.json:/var/docat/doc/config.json`\n\nSupported config options:\n\n```json\n{\n  \"headerHTML\": \"\u003ch1 style='color: #115fbf;'\u003eCustom Header HTML!\u003c/h1\u003e\",\n  \"footerHTML\": \"CONTACT: \u003ca href='mailto:maintainer@mail.invalid'\u003eMaintainers\u003c/a\u003e\"\n}\n```\n\n#### System Config\n\nFurther proxy configurations can be done through the following environmental variables:\n\n| Variable | Default | Description |\n|---|---|---|\n| `MAX_UPLOAD_SIZE` | [100M](./Dockerfile) | Limits the size of individual archives posted to the API |\n\n\n## Local Development\n\nFor local development, first configure and start the backend (inside the `docat/` folder):\n\n```sh\n# create a folder for local development (uploading docs)\nDEV_DOCAT_PATH=\"$(mktemp -d)\"\n\n# install dependencies\npoetry install --all-groups\n\n# run the local development version\nDOCAT_SERVE_FILES=1 DOCAT_STORAGE_PATH=\"$DEV_DOCAT_PATH\" poetry run python -m docat\n```\n\nAfter this you need to start the frontend (inside the `web/` folder):\n\n```sh\n# install dependencies\nyarn install --frozen-lockfile\n\n# run the web app\nyarn serve\n```\n\nFor more advanced options, have a look at the\n[backend](docat/README.md) and [web](web/README.md) docs.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdocat-org%2Fdocat","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdocat-org%2Fdocat","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdocat-org%2Fdocat/lists"}