Skip to content
merlinz01Public

About

Self-hosted knowledgebase software

Topics

Resources

Stars

2 stars

Watchers

0 watching

Forks

Repository files navigation

Gnotus

logo

Gnotus is an open-source, permissively licensed, and self-hosted knowledge-base software for both public and internal documentation.

License Contributors Repo Size Top Language

CI Build GitHub Issues GitHub Closed Pull Requests Last Commit

Docker Pulls GitHub Stars GitHub Forks

Table of Contents

Features

  • 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

Deployment

The recommended way to install Gnotus is with Docker Compose.

  1. 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.

  2. Configure the environment variables

    Create a .env file in the same directory as compose.yml with 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_ (see backend/app/settings.py for the available options). Add them to the environment section of the backend service in compose.yml.

  3. Start the services

    docker compose up -d

    This will download the necessary Docker images, and start everything for you.

  4. 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-user

    Follow the prompts to set up your admin user.

  5. 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.

  6. (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.yml in the same directory as compose.yml with 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.

Development

(Recommended) With Docker Compose

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 background

This 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>

Without Docker Compose

You can also set up the development environment without Docker Compose, but this requires more manual setup.

Backend Setup

  1. Install Python dependencies

    This project uses the uv package manager.

    cd backend
    uv sync
  2. Configure environment

    Settings are read from environment variables prefixed with GNOTUS_, which you can put in a .env file in the backend directory. See app/settings.py for the available options.

  3. Activate the virtual environment

    source .venv/bin/activate
  4. (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_search option set to true in the configuration file or the GNOTUS_DISABLE_SEARCH environment variable set to true. 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_URL and GNOTUS_MEILISEARCH_API_KEY environment 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
  5. Run the backend server

    fastapi dev

    The app will be available at http://localhost:8000 and will auto-reload when you modify backend code.

Project layout

The backend serves both the API (under /api) and the pages:

  • backend/app/pages/ renders the pages with the Jinja templates in backend/app/templates/. Each page is also available as a partial (with ?_partial=1) containing just its content.
  • backend/app/static/app.js swaps 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.

License

Gnotus is licensed under the MIT License. See LICENSE.txt for details.

About

Self-hosted knowledgebase software

Topics

Resources

Stars

2 stars

Watchers

0 watching

Forks

Used by

Contributors

Languages