Skip to content
Get packs

Guide · Open source

How to use Docs: install, run locally and write with it

Updated · written with AI from the project's own documentation and checked against our catalogue data

Docs is an open-source, web-based collaborative editor from the suitenumerique project, built with Django and React. It lets people write, organize and share documents together in real time, and nest subpages to build a knowledge base. This guide explains what Docs offers, how to run it locally with Docker and GNU Make, and what to check before you rely on it.

Docssuitenumerique/docs · ★ 17k · MIT

Quick start

  1. 1Install prerequisites. Install Docker, Docker Compose and GNU Make, then check Docker with docker -v and docker compose version.
  2. 2Clone the repository. Run git clone https://github.com/suitenumerique/docs to get the source code.
  3. 3Bootstrap the project. Run make bootstrap FLUSH_ARGS='--no-input' to build containers, install dependencies and run migrations.
  4. 4Start services. Run make run, then open https://localhost:3000 in your browser.
  5. 5Create an admin user. Run make superuser if you need access to the Django admin at localhost:8071/admin.
  6. 6Create demo content (optional). Run make demo to create a basic demo site for testing.

What can you do in Docs?

Docs covers three areas: writing, collaboration and knowledge management. You can write with rich-text and Markdown editing, use slash commands and blocks, and edit offline. Several people can work on the same document with live cursors, comments and granular access control.

Documents can contain subpages, so you can build a hierarchy for a wiki or knowledge base. Content is searchable.

  • Rich-text and Markdown editing with slash commands
  • Live cursors, presence, comments and sharing
  • Subpages and hierarchy for knowledge organisation
  • Import .docx and .md; export .docx, .odt and .pdf

Choose between a public instance and self-hosting

You can try Docs without installing anything by opening the live demo or browsing public instances listed in the project documentation. Public instances are run by others, so you need to find and trust one yourself.

If you want control over where your data lives, self-host Docs. The project supports Kubernetes, Docker Compose, and community-provided methods such as Nix and YunoHost. Self-hosting means you run the infrastructure yourself.

Set up a local development instance

The README's local setup is intended for development and testing only. Install Docker, Docker Compose and GNU Make first, then confirm Docker is available. If you get permission errors, you may need sudo or to add your user to the docker group.

  • Clone the repository from GitHub
  • Run the bootstrap command, which builds the app-dev and frontend-dev containers, installs dependencies, runs migrations and compiles translations
  • Start the services with make run
  • Open https://localhost:3000
git clone https://github.com/suitenumerique/docs make bootstrap FLUSH_ARGS='--no-input' make run

Sign in and create a superuser

The development setup provides default credentials, which are for development only. Change them before any real use. To create an administrator account for the Django admin, run the superuser command, then open the admin UI.

  • Default development login: username impress, password impress
  • Admin UI is at http://localhost:8071/admin
make superuser

Run the frontend or backend separately

For frontend work, the README suggests running outside Docker. For backend-only work, you can start every service except the frontend container. Backend tests can also run without Docker, which helps when configuring PyCharm or VSCode, though some URL and port values must be overridden.

make frontend-development-install make run-frontend-development make run-backend

Handle licensing for PDF export

Docs is released under the MIT License. Some advanced features, such as Export as PDF, rely on BlockNote XL packages that are GPL-licensed and not MIT-compatible. To build an image without those features, the README says to build with PUBLISH_AS_MIT=true. Check this before you depend on PDF export.

PUBLISH_AS_MIT=true

What people use it for

  • Running a shared internal wiki or knowledge base on your own infrastructure
  • Letting a team co-edit documents with live cursors and comments
  • Writing documents with subpages organised as a hierarchy
  • Pushing meeting transcripts from a Meet instance into Docs for the requesting user, using a server-to-server API token
  • Developing and extending a Django and React application

Frequently asked questions

Is Docs free and open source?

Yes. The project is released under the MIT License. Some advanced features, such as PDF export, use GPL-licensed BlockNote XL packages unless you build with PUBLISH_AS_MIT=true.

What do I need to install Docs locally?

The README lists Docker, Docker Compose and GNU Make as prerequisites. You clone the repository and run make bootstrap, then make run.

How do I start Docs after installing?

Run make bootstrap FLUSH_ARGS='--no-input' once, then make run, and open https://localhost:3000. The README gives default development credentials of impress and impress.

Can I use Docs without installing it?

Yes. The project links a live demo document and a list of public instances. Public instances are run by others, so check that you trust the host before storing data there.

Does Docs support PDF export?

The source says PDF export is available as an advanced feature, but it relies on non-MIT BlockNote XL packages. If you need an MIT-only build, the README says to build with PUBLISH_AS_MIT=true, which excludes those features.

How does Docs compare to Outline, BookStack or Wiki.js?

The README describes Docs as an alternative to Notion and Google Docs, focused on real-time collaboration and self-hosting. It does not compare it to Outline, BookStack, AppFlowy or Wiki.js, so evaluate those against your own requirements.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

Docs suits teams and public bodies that want a self-hosted, real-time collaborative wiki under an MIT licence, and developers who want to extend a Django and React app. It is a poor fit if you only need a quick document with no setup, or if you want a fully managed service with no infrastructure work.

Install options & downloads