Run a collaborative Docs development environment locally, verify it, and make it reachable for controlled remote testing
La Suite Docs is an open-source, web-native editor for collaborative documents, structured knowledge, comments, and real-time editing. This guide installs the official development and testing environment with Docker Compose and GNU Make, verifies the application at its documented local endpoint, and covers useful development operations. After the local instance works, we configure a separate Localtonet HTTP tunnel so authorized remote testers can reach it without inbound router port forwarding, firewall changes, a VPN, or a public IP address. The workflow documented here is for development and testing, not an evidenced production deployment.
📋 What's in this guide
What this setup provides
La Suite Docs is an open-source collaborative text editor designed for writing, organizing, and sharing knowledge. Its documented capabilities include real-time collaboration, live cursors and presence, comments, structured documents and subdocuments, block-based editing, search, sharing, granular access control, and import or export workflows. It is built with open-source components that include Django REST Framework, Next.js, Yjs, ProseMirror, BlockNote.js, and HocusPocus.
The project supports self-hosting with Docker Compose and Kubernetes. Community-maintained Nix and YunoHost methods are also mentioned by the project. However, the commands covered in this article are specifically the repository's local development workflow. The project explicitly describes this environment as suitable for development and testing only. It uses MinIO as an S3-compatible storage backend, although the project notes that other S3-compatible services can be used in an appropriately configured deployment.
That distinction matters. A development stack is convenient because its containers, dependencies, database migrations, translations, frontend, backend, and supporting services can be prepared together. It is not automatically a production architecture. Production decisions such as durable storage, backups, identity integration, domain configuration, email delivery, monitoring, scaling, upgrade policy, and secret management require the project's production installation guidance and an environment-specific review.
https://localhost:3000.
How the traffic path changes
Before adding remote access, a browser on the host connects directly to the Docs frontend on local port 3000. After adding Localtonet, the Localtonet client establishes an outbound connection to one of our relay servers. The public address assigned to the tunnel forwards requests to the configured local IP address and port. This means the host does not need an inbound router port-forwarding rule, a public IP address, firewall changes, or a VPN merely to publish the web endpoint.
The Localtonet tunnel does not install or configure Docs, and creating a tunnel does not mean it is running. Docs must already be healthy locally. The selected Localtonet device must then be connected, and the tunnel must be started. If the application stops, the client disconnects, or the tunnel is stopped, remote users will no longer receive a working Docs page.
Always verify https://localhost:3000 from the Docs host before creating the tunnel. This separates application problems from remote-access problems and makes troubleshooting much faster.
Prerequisites and host preparation
The official local development workflow requires Docker, Docker Compose, and GNU Make. You also need Git if you plan to obtain the source with the documented git clone command. Install these tools using the supported installation method for your operating system. The available package names and Docker installation steps vary across Linux distributions, macOS, and Windows, so this article does not invent a universal package-manager command.
On systems where GNU Make is not normally included, install it before continuing. Windows users should choose an environment in which Docker Compose and GNU Make can operate consistently against the cloned repository. The project evidence supplied for this guide does not establish a specific Windows shell, virtualization configuration, CPU architecture list, minimum memory value, or minimum disk allocation. Check the current project and Docker requirements before standardizing this setup across multiple machines.
| Requirement | Purpose | How to validate it |
|---|---|---|
| Docker | Builds and runs the application's containers and supporting services. | docker -v |
| Docker Compose | Coordinates the multi-container development stack. | docker compose version |
| GNU Make | Runs the repository's documented bootstrap, startup, test, and maintenance targets. | make --version |
| Git | Clones the repository and supports later source updates. | git --version |
| Local port 3000 | Serves the documented development web application. | Confirm that another local program is not already occupying the port. |
| Local port 8071 | Provides the documented Django administration endpoint. | Keep it local unless a separately reviewed administrative access design requires otherwise. |
Verify the command-line tools
Open a terminal and run the following checks. Version text should be returned for each installed tool. The Docker commands also need access to a functioning Docker installation.
docker -v
docker compose version
make --version
git --version
If docker -v succeeds but later Docker operations report a connection or permission error, confirm that the Docker service or Docker Desktop is running. The Docs project notes that some users may need to run Docker with elevated privileges or add their account to the Docker group. Group membership changes have security implications because Docker access can provide extensive control over the host, so follow the Docker guidance for your operating system rather than applying an unreviewed permission change.
The documented account uses the development-only username impress and password impress. Treat these credentials as public knowledge. Keep the service local while installing and validating it, and do not use this default account for sensitive content or uncontrolled public access.
Install and start La Suite Docs with Docker Compose
The official development path is intentionally short at the command line, but the bootstrap target performs substantial work. It builds the development application and frontend containers, installs dependencies, runs database migrations, and compiles translations. Run the commands from a location where your account can create the repository directory and where Docker has enough resources to build the containers.
Clone the Docs repository
Obtain the source from the official repository and enter the project directory.
git clone https://github.com/suitenumerique/docs.git
cd docsBootstrap the development environment
Run the documented bootstrap target. Keep the quoting intact so the FLUSH_ARGS value is passed as intended.
make bootstrap FLUSH_ARGS='--no-input'
This builds the app-dev and frontend-dev containers, installs dependencies, applies database migrations, and compiles translations. The project recommends running this command again after pulling new code.
Start the services
Start the development stack from the repository directory.
make runKeep the terminal open if the process remains attached and displays service output. Wait for the stack to initialize before opening the application.
Open the web application
On the host running the containers, open https://localhost:3000 in a browser. Use the documented development credentials only for this local test: username impress and password impress.
The bootstrap process may take time during its first run because Docker can need to download base images, build project images, and install dependencies. A later run may reuse cached layers. Build duration and resource consumption depend on the host and are not fixed by the available project evidence, so avoid promising a specific completion time.
Licensing consideration for optional functionality
The project warns that some advanced features, including PDF export, rely on BlockNote XL packages licensed under the GPL and not compatible with an MIT-only build. The project documents PUBLISH_AS_MIT=true as a build setting that produces Docs without the non-MIT features. Licensing requirements depend on how an organization modifies, redistributes, or operates the software. Review the project's current licensing details before making a deployment policy decision.
Do not add the setting casually to the commands above, because doing so changes the resulting feature set. The unmodified development command is the appropriate path when the objective is to reproduce the project's documented contributor environment.
Verify the local application before remote access
A successful make run command is encouraging, but local verification should test the browser experience rather than relying only on terminal output. Open the exact documented endpoint from the same machine:
https://localhost:3000Confirm that the page loads and that you can reach the sign-in flow. For the development environment, enter the documented username and password:
Username: impress
Password: impressAfter signing in, perform a small functional test. Create or open a test document, enter non-sensitive text, and confirm that the editor responds. If you intend to evaluate collaboration, use separate authorized browser sessions and test only with disposable content. A tunnel cannot correct a failing frontend, an unavailable backend, a database migration problem, or an object-storage issue, so this local test is an essential boundary in the workflow.
A practical verification checklist
https://localhost:3000 and receives the Docs interface rather than a connection error.
Docs documents its development endpoint as https://localhost:3000. When configuring remote access, select the current Localtonet HTTP/s option that matches the local service protocol. If the dashboard or client version distinguishes an HTTPS local origin from a plain HTTP origin, use the HTTPS-compatible setting. Do not silently change the local endpoint to HTTP without confirming that the running Docs environment actually supports it.
Keep Django administration separate
The repository documents the Django administration interface at http://localhost:8071/admin. It also provides a command for creating a superuser:
make superuserThe administration endpoint is not the normal collaborative editor and should not ordinarily be exposed through the public tunnel created in this guide. Administrative interfaces deserve stricter access controls, separate credentials, careful audit practices, and a deliberately reviewed access path. The tunnel target later in this article is the user-facing application on port 3000, not the administration interface on port 8071.
Common development operations
The repository includes Make targets for common contributor workflows. Run them from the cloned docs directory. Because available targets can change as the project evolves, make help is the documented way to inspect the rules provided by the checked-out version.
make helpAdd demonstration content
To create a basic demonstration site, use:
make demoDemonstration content is useful when evaluating navigation and document organization, but it should remain disposable. Confirm what the current project version creates before using the command against any environment containing data you intend to preserve.
Run frontend development outside Docker
For frontend work, the project documents an installation target followed by a dedicated frontend development target:
make frontend-development-install
make run-frontend-development
This mode can be more convenient when iterating on frontend code. It is a distinct workflow from the complete containerized startup path, so use it when actively developing the frontend rather than as an unexplained replacement for make run.
Start the backend stack without the frontend container
When a separately running frontend will connect to the backend services, start all documented services except the frontend container with:
make run-backendRun frontend checks
The project provides separate targets for frontend tests and linting:
make frontend-test
make frontend-lint
Backend tests can also be run outside Docker, which can help editor and IDE integrations. The project notes that removing Docker from the testing path requires overriding URL and port values that differ inside and outside containers. The relevant variables are maintained under env.d/development/common, with test-specific overrides under env.d/development/common.test. This guide does not invent replacement values because they must match the checked-out project version and the developer's environment.
Update a development checkout
When you deliberately update the source to a newer revision, review the project's release notes and upgrade guidance first. After pulling new code, the project recommends running the bootstrap command again:
make bootstrap FLUSH_ARGS='--no-input'Re-bootstrap before investigating unusual frontend dependency, migration, or translation behavior caused by a source update. For a shared or important environment, preserve needed data before performing upgrades. The development commands supplied here do not constitute a backup policy.
Stop or restart the stack carefully
The supplied project evidence does not identify a canonical Make target for stopping, destroying, or resetting this exact development stack. Do not guess a destructive command. Run make help against your checkout and use the target documented there. If make run is attached to the current terminal, an ordinary terminal interruption may end the foreground process, but verify container state before assuming every supporting service has stopped.
Docker cleanup or volume-removal commands can delete development databases and stored files. Use only a project-documented reset or teardown target after confirming what data it removes.
Provide controlled remote HTTP access with Localtonet
Add Localtonet only after the Docs page works locally. Our client runs on the machine that hosts the service, or on another device that can reach the service over the local network. It establishes an outbound connection to our relay server. An HTTP/s tunnel then provides a public HTTPS address for the configured local target.
For the same-machine setup in this guide, the intended target is the Docs frontend at local address 127.0.0.1 and port 3000. The application documents this endpoint with HTTPS, so ensure the current tunnel configuration is compatible with an HTTPS local origin. Localtonet options can vary by client version, plan, and current dashboard. Obtain the available relay server values and HTTP/s choices from the current product rather than copying a hardcoded region or undocumented field from an old tutorial.
Install and run the Localtonet client
Install our client for the operating system on the device that can reach https://127.0.0.1:3000. Start the client and keep it running for as long as remote access is required.
Authenticate or select the device
Use the device-specific authentication token provided through your Localtonet account, or select the corresponding connected device in the dashboard. Never place the token in documentation, screenshots, shell history, source control, or a shared message.
Select an available relay server
Choose an available server or region from the current dashboard. Server codes and availability must be obtained from the product at configuration time and should not be hardcoded from an unrelated example.
Create an HTTP/s tunnel to Docs
Create the appropriate HTTP/s configuration and set the local target to 127.0.0.1 on port 3000. Because Docs documents the local endpoint as HTTPS, select the current option that supports the actual local origin protocol. Use a generated subdomain for straightforward testing unless you have separately verified the current requirements for a selected subdomain or custom domain.
Start the tunnel
Creating the configuration does not start it. Press the documented Start control and wait for the selected device and tunnel to report a connected or running state.
Test the assigned public address
Open the assigned public HTTPS URL from a separate network or authorized test device. Confirm that it reaches the Docs frontend, then stop or delete the tunnel when remote access is no longer required.
For the current product workflow, consult our Localtonet HTTP tunnel documentation. The dashboard is authoritative for available relay servers, process types, plan-dependent options, and client-version-specific controls.
| Endpoint or component | Recommended treatment | Reason |
|---|---|---|
| Docs frontend on port 3000 | Use as the tunnel target for controlled testing. | This is the documented user-facing development endpoint. |
| Django admin on port 8071 | Keep local by default. | It is an administrative interface and is not needed for normal document collaboration. |
| Database and storage services | Do not create public tunnels for them. | Supporting infrastructure should remain private and reachable only by the components that require it. |
| Localtonet device token | Store privately and rotate it if exposed. | The token identifies the client device that can run tunnels. |
| Public tunnel URL | Share only with intended testers. | Anyone who can reach the address can attempt to interact with the exposed application. |
Security boundaries for a remote development instance
A public URL changes the exposure of the application. It does not convert development defaults into production-grade controls. The default development credentials are documented publicly, so the login page itself should not be considered meaningful protection for an internet-reachable test instance. Use the shortest practical exposure window, share the URL narrowly, avoid real organizational data, and stop the tunnel immediately after the test.
Docs states that documents are not currently end-to-end encrypted and warns that the application is not suitable for classified or highly restricted content. Transport protection and application-level end-to-end encryption solve different problems. A public HTTPS address can protect traffic in transit to the tunnel edge, but it does not make document content end-to-end encrypted between collaborators.
Do not upload confidential files, credentials, regulated records, classified material, production exports, or secrets. The environment is documented for development and testing, its default credentials are known, and the application does not currently provide end-to-end document encryption.
Apply least exposure
Expose only the application port required for the test. Do not publish Docker management sockets, databases, MinIO administration, backend-only services, or the Django administration interface. A single application tunnel is easier to review and revoke than a collection of public infrastructure endpoints.
Remote access also does not authorize a user to ignore workplace policy, data handling requirements, or the permission of the network owner. Confirm that publishing the development service is allowed. If the application will be used beyond a controlled test, replace the development workflow with the project's production self-hosting approach and conduct a deployment-specific security review.
Protect the Localtonet device token
A Localtonet authentication token is device-specific. Do not paste it into this repository, a Compose file, an issue, a build log, a tutorial screenshot, or a chat room. If a token is exposed, treat it as compromised and use the current account controls to replace it. This article intentionally does not include an example token.
Understand tunnel availability
The public address works only while the selected client is connected and the tunnel is running. This lifecycle is useful for temporary testing because stopping the tunnel removes the public path without changing the Docs containers. Deleting the tunnel removes its configuration. Stopping Docs while leaving the tunnel active will normally leave a public address with no healthy local application behind it, so stop both parts when the session ends.
Troubleshooting the installation and tunnel
Docker commands are unavailable
If the shell reports that docker is not found, Docker is either not installed or is not present in the current command path. If docker compose is unavailable, confirm that the modern Compose integration is installed. The project specifically verifies Compose with docker compose version, not the older standalone command spelling.
Docker reports a daemon or permission error
Start the Docker service or Docker Desktop and repeat the version checks. On systems that restrict access to the Docker daemon, follow the platform's supported permission procedure. The project mentions elevated privileges or Docker group membership as possible remedies, but do not weaken host security without understanding the consequence.
The bootstrap target fails
Read the first meaningful error rather than only the final Make failure. Common categories can include image download failures, insufficient host resources, dependency installation errors, unavailable services, or Docker permission problems. The available evidence does not establish a universal remedy for each possible build error. After correcting the underlying problem, rerun:
make bootstrap FLUSH_ARGS='--no-input'If the failure follows a source update, confirm that you are in the repository root and that you re-ran the recommended bootstrap command after pulling the new code.
Port 3000 is already occupied
Stop the unrelated process using the port or adjust the development configuration according to the checked-out project's documented environment variables. This guide does not provide an invented alternate port mapping because changing one component can affect frontend URLs, backend expectations, callbacks, and tunnel settings. If you intentionally configure another port, use that same verified port as the Localtonet target.
The browser cannot open the local endpoint
Confirm that make run is still active and inspect its terminal output. Verify that the address includes the documented scheme and port: https://localhost:3000. Do not troubleshoot Localtonet until the page works on the host itself.
The local page works but the public URL does not
Check the workflow in order:
- Confirm that the Localtonet client device reports connected.
- Confirm that the HTTP/s tunnel has been started, not merely created.
- Confirm that the target is the Docs frontend on
127.0.0.1:3000. - Confirm that the tunnel's local origin protocol matches the HTTPS service documented by Docs.
- Confirm that
https://localhost:3000still works directly on the client device. - Confirm that the tested URL is the current public address assigned to the running tunnel.
If the Localtonet client is running on a different machine from Docker, 127.0.0.1 points to the client machine itself, not to the Docker host. In that topology, configure a reachable LAN address for the Docs host only after confirming the application's listening behavior and local network policy. The supplied project evidence does not establish a universal LAN binding, so do not assume that the development service accepts connections from other devices.
The public page opens but collaboration behaves unexpectedly
First reproduce the behavior locally in multiple authorized browser sessions. Real-time collaboration can involve more than an initial page request, so a partially loading interface does not prove that every application connection is healthy. Inspect the current Docs service output and current Localtonet HTTP tunnel behavior. Avoid inventing proxy-header or WebSocket settings without confirming them against the checked-out Docs version and our current HTTP tunnel documentation.
The Django administration page is unavailable remotely
That is expected in this design. The tunnel targets port 3000, while the documented admin endpoint is on port 8071. We intentionally do not expose the administrative interface. Access it locally at http://localhost:8071/admin when administration is necessary.
An update introduces unexpected behavior
Review the release and upgrade information for the version you selected, then run the recommended bootstrap command after pulling code. A named release should not be assumed to behave exactly like the current main branch. For repeatable team testing, record the commit or release under review without claiming that this development recipe is a production version-pinning strategy.
Frequently asked questions
Is this La Suite Docs setup suitable for production?
No. The project explicitly identifies the commands in this guide as a development and testing workflow. Docs supports production self-hosting through Docker Compose and Kubernetes, but production deployment requires the current installation guidance plus environment-specific decisions about identity, persistent storage, backups, domains, email, secrets, monitoring, upgrades, and security.
Which local address should I open after starting Docs?
Open https://localhost:3000 on the machine running the development environment. Verify that endpoint before adding a Localtonet tunnel.
What are the default development credentials?
The documented username is impress and the documented password is impress. These credentials are for development only and are publicly known. Do not rely on them to protect sensitive data or an uncontrolled internet-facing instance.
Does Localtonet require router port forwarding or a public IP?
No. Our client establishes an outbound connection to a Localtonet relay server. This allows the tunnel to provide a public URL without inbound router port forwarding, firewall changes, VPN setup, or a public IP address.
Does creating a Localtonet tunnel immediately make Docs public?
No. Creating a tunnel and running it are separate lifecycle actions. The selected client must be connected, and you must start the tunnel. The public route remains usable only while the application, client, and tunnel are running.
Should I expose the Django admin endpoint through the same tunnel?
No. The tunnel in this guide targets the user-facing Docs application on port 3000. The Django admin endpoint is documented separately at http://localhost:8071/admin and should remain local unless a separately reviewed administrative access design requires remote availability.
Can I store confidential or classified documents in this test instance?
You should not. The development environment has publicly documented credentials, and Docs states that documents are not currently end-to-end encrypted. The project specifically warns that it is not suited for classified or highly restricted content. Use disposable, non-sensitive test data.
Why should I run the bootstrap command after pulling new code?
The bootstrap target builds the development application and frontend containers, installs dependencies, runs database migrations, and compiles translations. Re-running it after source updates helps align those generated and installed components with the updated checkout.
Can the Localtonet client run on another device?
Yes, a Localtonet local target can be a service reachable from the client device. However, 127.0.0.1 always refers to the device running the client. If Docs runs elsewhere, use a verified reachable address and confirm that Docs is listening on an appropriate network interface. The evidence for this development setup does not establish a default LAN binding, so test that topology locally before creating the tunnel.
Connect your verified Docs test instance with Localtonet
Start by confirming that La Suite Docs works at https://localhost:3000. Then use our HTTP/s tunneling workflow to create a temporary public address for controlled remote development or testing, without configuring inbound router port forwarding.
