Gnotus is an open-source, permissively licensed, and self-hosted knowledge-base software for both public and internal documentation.
- Light-weight server-rendered pages with fast in-page navigation, built with FastAPI and plain JavaScript (no frontend build step).
- Browser caching for fast page loads
- In-app document creation and editing
- Markdown document format
- Upload management for images and other files
- Optimized for search engine indexing
- Supports both light and dark mode
- Responsive design for mobile, desktop, and print
- Customizable site branding with colors and logo
- Automatic table of contents generation
- Document history with the ability to revert to previous versions
- Public and private documents
- Full-text search, including in private documents
- In-app user management with various user roles
The recommended way to install Gnotus is with Docker Compose.
-
Download the Docker Compose file
curl -L https://raw.githubusercontent.com/merlinz01/gnotus/main/compose.yml -o compose.yml
The frontend service publishes ports 80 and 443.
-
Configure the environment variables
Create a
.envfile in the same directory ascompose.ymlwith the following content:# .env # The domain name of your Gnotus instance. # If you are serving Gnotus on a public domain, set this to your domain name. CADDY_DOMAIN=my.domain.com # The email address to use for Let's Encrypt registration. # This is required for the Caddy service to obtain SSL certificates. CADDY_EMAIL=me@example.com # GNOTUS_BASE_URL is the base URL of your Gnotus instance. # If you are serving Gnotus on a public domain, set this to your domain name. GNOTUS_BASE_URL=https://my.domain.com # The secret key for the backend and search services. # This must be changed to a long, securely generated random string, # for example the output of `openssl rand -base64 32`. SECRET_KEY=your-secret-key
The backend accepts other settings as environment variables prefixed with
GNOTUS_(seebackend/app/settings.pyfor the available options). Add them to theenvironmentsection of the backend service incompose.yml. -
Start the services
docker compose up -d
This will download the necessary Docker images, and start everything for you.
-
Create the initial admin user
After the services are up and running, you can create the initial admin user by running the following command:
docker compose exec backend ./manage.sh create-userFollow the prompts to set up your admin user.
-
Access the application
You can now access the Gnotus application at
http://localhost(or your configured domain if you set it up for public access).You can log in with the admin user you just created. Then go to Administration > Search Index and click Rebuild Index to set up the search index. Do the same after restoring a backup, or if search results are missing or out of date.
-
(Optional) Configure IPv6
If your server is reachable via IPv6, it is recommended to configure IPv6 in Docker so that logging and rate limiting work correctly. (If you don't do this, the Caddy service will see all IPv6 requests as coming from the internal Docker gateway, which will mean that all IPv6 requests will be rate-limited as if they were all from the same IP address.)
To do this, add the following line to your Docker daemon configuration file (usually located at
/etc/docker/daemon.json):{ "ip6tables": true }Then restart the Docker service (you may want to stop the Docker Compose services first):
sudo systemctl restart docker
Create a new file
compose.override.ymlin the same directory ascompose.ymlwith the following content:networks: default: enable_ipv6: true ipam: config: - subnet: <your_ipv6_subnet> # e.g. "2001:db8:1::/64"
Replace
<your_ipv6_subnet>with your actual IPv6 subnet.Finally, restart the Docker Compose services:
docker compose down docker compose up -d
Now the Caddy service should be able to correctly log and rate limit IPv6 requests.
If you want to develop Gnotus, the recommended way is to use Docker Compose to set up the development environment. Simply run the following command in the root directory of the project:
docker compose -f compose.dev.yml up --build
# Add the `-d` flag to run in the backgroundThis will start the backend and the search service in development mode.
On startup, the backend applies any pending database migrations.
To index the documents for search, go to Administration > Search Index and click Rebuild Index.
The app will be available at http://localhost:5173, and will reload when you modify the backend code, templates, styles or scripts.
If you want to override settings, you can set them as environment variables in a .env file in the backend directory.
If you need to run commands in the backend service, you can use the following command:
docker compose -f compose.dev.yml exec backend <command>You can also set up the development environment without Docker Compose, but this requires more manual setup.
-
Install Python dependencies
This project uses the
uvpackage manager.cd backend uv sync -
Configure environment
Settings are read from environment variables prefixed with
GNOTUS_, which you can put in a.envfile in thebackenddirectory. Seeapp/settings.pyfor the available options. -
Activate the virtual environment
source .venv/bin/activate -
(Optional) Start Meilisearch
If you want to test the full-text search functionality, you can run Meilisearch in a Docker container. This is optional, as Gnotus can run without it with the
disable_searchoption set totruein the configuration file or theGNOTUS_DISABLE_SEARCHenvironment variable set totrue. Note that disabling search will prevent you from using the search functionality in the app and will cause the search index to become out of sync with the documents if previously indexed.docker run -d --name meilisearch -p 7700:7700 getmeili/meilisearch:v1.15
Make sure to set the
GNOTUS_MEILISEARCH_URLandGNOTUS_MEILISEARCH_API_KEYenvironment variables (or the corresponding options in your configuration file) to connect to Meilisearch.To index all documents in Meilisearch, go to Administration > Search Index in the app, or use the following command:
python -m app.manage index
To stop and remove the Meilisearch container, you can run:
docker stop meilisearch docker rm meilisearch
-
Run the backend server
fastapi dev
The app will be available at
http://localhost:8000and will auto-reload when you modify backend code.
The backend serves both the API (under /api) and the pages:
backend/app/pages/renders the pages with the Jinja templates inbackend/app/templates/. Each page is also available as a partial (with?_partial=1) containing just its content.backend/app/static/app.jsswaps those partials into the page when navigating, caches them for instant repeat visits, and implements the interactive parts of the pages. It is served as-is, without a build step.backend/app/static/css/contains the styles, which the backend bundles into one stylesheet.frontend/contains the Caddy configuration for the reverse proxy used in production.
The JavaScript and CSS are formatted with Prettier using the configuration in .prettierrc.json.
Gnotus is licensed under the MIT License. See LICENSE.txt for details.