Set Up DevDocs with Docker and Localtonet

What DevDocs is and what this setup provides

DevDocs is an API documentation browser that brings multiple developer reference sets into one organized web interface. Its focus is fast access to API and reference material rather than long-form programming tutorials. The interface includes instant search, a mobile version, dark theme support, keyboard shortcuts, and offline functionality. Users can select the documentation sets they need instead of loading every available reference into the browser.

The application has two major pieces. A Ruby scraper generates documentation and metadata, while a client-side JavaScript application presents that content through a small Sinatra and Sprockets application. Search and much of the application behavior happen in the browser. DevDocs also uses browser features including a service worker and localStorage to improve startup behavior and support its offline-oriented design.

For readers who only need the maintained public service, the DevDocs project recommends its hosted site. Self-hosting is useful when we want a locally controlled endpoint, a repeatable internal deployment, or a server that can be made available to a particular remote workflow on demand. It does not change DevDocs into a tutorial platform or a full-text search engine. Its content remains focused on structured API and reference documentation pulled from upstream sources.

Prerequisites and deployment plan

The recommended path requires a machine with Docker installed and running. The machine must be able to download an image from GitHub Container Registry, and host port 9292 must be available. You also need a recent compatible browser. The DevDocs project lists recent Firefox, Chrome, or Opera versions, Safari 11.1 or later, Edge 17 or later, and iOS 11.3 or later as its browser baseline.

Docker installation differs across Windows, macOS, and Linux, so this guide does not invent a platform-specific package command. Complete the supported Docker installation for your operating system, start its engine, and then confirm that the client can communicate with the engine:

docker version
docker ps

The first command reports Docker client and server information. The second should return a container list, even if the list is empty. A permission error, missing command, or inability to connect to the daemon must be resolved before installing DevDocs.

Check whether another container already uses the intended name:

docker ps -a --filter name=devdocs

You should also check whether port 9292 is already assigned to another application. The exact operating-system command for inspecting ports varies, but a practical cross-platform check is to look at the published ports of running Docker containers:

docker ps

If an existing service already owns host port 9292, stop or reconfigure that service before following the exact recommended DevDocs command. Although Docker can map a different host port to container port 9292, the official quick-start evidence specifically documents 9292:9292. This guide keeps that mapping so the expected endpoint remains unambiguous.

Additional requirements for remote access

Localtonet is a separate next step, not a substitute for installing DevDocs. For that stage, install and run our client application on the same device as DevDocs, or on another device that can reach the DevDocs host and port. You need a device-specific Localtonet authentication token and must select a relay server or region from the current dashboard. Tokens and server codes must come from your account and current product interface. Do not copy placeholder values from articles or expose a real token in screenshots, terminal history, source control, or support messages.

Install DevDocs with the official Docker image

The DevDocs project recommends Docker as the easiest local installation method. The published standard image is ghcr.io/freecodecamp/devdocs:latest. An Alpine-based image is also available as ghcr.io/freecodecamp/devdocs:latest-alpine. The Alpine variant is described as smaller, but the standard image is the clearest starting point because it is used in the project's primary quick-start command.

docker run --name devdocs -d -p 9292:9292 ghcr.io/freecodecamp/devdocs:latest

docker ps --filter name=devdocs
docker logs devdocs

The --name devdocs argument assigns a stable container name, making later start, stop, log, and removal commands easier. The -d argument runs the container in the background. The -p 9292:9292 argument publishes container port 9292 as host port 9292. The final argument identifies the standard published image.

Verify the DevDocs service before exposing it

Verification should cover more than seeing an open browser tab. Confirm the container state, the HTTP response, the main interface, a documentation set, and normal browser behavior. This separates application problems from tunnel problems and makes later troubleshooting much faster.

Check the container state

docker ps --filter name=devdocs

The result should show the devdocs container as running and should display the port publication for 9292. If the container is absent from the running list, inspect all containers and its logs:

docker ps -a --filter name=devdocs
docker logs devdocs

A container can be created successfully and still stop because of a runtime problem. This distinction matters: a created container is not evidence that the web application is currently available.

Test the local HTTP endpoint

Open the following address on the Docker host:

http://localhost:9292

Confirm that the DevDocs interface appears. Test search, open a reference entry, navigate between pages, and reload the application. DevDocs is heavily browser-based, so a basic server response alone does not prove that all client-side behavior works.

If you use the manual installation path described later, the project notes that the first request can take a few seconds while assets compile. The published container path may have different startup characteristics, so avoid assigning a fixed readiness time that the project does not document. Review the logs and retry after the container has started rather than treating one immediate failure as conclusive.

Check the intended documentation sets

DevDocs lets users choose their own collection of documentation. Verify that the references needed by your team or workflow are available and usable. Do not assume that self-hosting turns DevDocs into a mirror of every tutorial, guide, or page from each upstream project. DevDocs intentionally focuses on API and reference content that fits its indexing model.

Routine Docker operations and updates

A self-hosted service needs a small operational playbook. Keep the container name stable, inspect logs before recreating it, and test each update locally before restoring remote access.

Stop and start DevDocs

docker stop devdocs
docker start devdocs

Stopping the container makes the local endpoint unavailable. Any Localtonet tunnel that still points to port 9292 will no longer have a working upstream service. Starting the Docker container again restores the local process, but you should verify the local URL before relying on remote access.

Restart the container

docker restart devdocs

A restart is useful after a transient runtime issue, but it is not an update. Restarting continues to use the image from which the current container was created.

Review logs

docker logs devdocs

To follow new output while testing the browser endpoint, use:

docker logs -f devdocs

Stop following the output with the terminal interrupt appropriate to your shell. Logs can help distinguish startup failures, application errors, and requests that never reached the container.

Replace the container with the current published image

DevDocs states that its published images are built and updated monthly with the latest documentation. Docker does not automatically replace an existing container merely because the tag now points to a newer image. A controlled replacement workflow is:

docker pull ghcr.io/freecodecamp/devdocs:latest
docker stop devdocs
docker rm devdocs
docker run --name devdocs -d -p 9292:9292 ghcr.io/freecodecamp/devdocs:latest

Verify http://localhost:9292 again after replacement. The official quick start does not document a volume mapping or a complete persistence and backup model for this container command, so this article does not invent one. If your browser or deployment depends on locally changed state, investigate and test that state explicitly before removing the old container.

Alternative installation paths

The published image is the recommended choice for a straightforward server. DevDocs also documents building the Docker image from source and performing a manual Ruby installation. These alternatives are useful for contributors, custom image workflows, or environments where the prebuilt image is not the intended deployment artifact.

Use the Alpine-based published image

The project publishes ghcr.io/freecodecamp/devdocs:latest-alpine as its smaller Alpine-based alternative. To use it with the same documented name and port mapping:

docker run --name devdocs -d -p 9292:9292 ghcr.io/freecodecamp/devdocs:latest-alpine

Do not run this while another container named devdocs exists or while host port 9292 is already occupied. Choose one image path, verify it, and keep the operational procedure consistent.

Build the Docker image from source

DevDocs documents the following source-build sequence:

git clone https://github.com/freeCodeCamp/devdocs.git && cd devdocs
docker build -t devdocs .
docker run --name devdocs -d -p 9292:9292 devdocs

The first command clones the repository and enters its directory. The second builds the repository Dockerfile into a local image tagged devdocs. The third starts a container from that local image. This does not provide automatic synchronization with later repository changes. To rebuild newer code, update the checkout, build again, replace the old container, and verify the result.

Install manually with Ruby

The documented manual path requires Ruby 4.0.6 as defined by the project Gemfile, libcurl, and a JavaScript runtime supported by ExecJS. The project notes that a suitable runtime is included on macOS and Windows, while Linux requires Node.js. Package names and installation commands vary by operating system, so verify those prerequisites through the operating system's current supported package channel.

After the prerequisites are installed, the documented application sequence is:

git clone https://github.com/freeCodeCamp/devdocs.git && cd devdocs
gem install bundler
bundle install
bundle exec thor docs:download --default
bundle exec rackup

Then open http://localhost:9292. The project notes that the first request can take several seconds to compile assets.

The documentation-management commands are also important for a manual deployment. List available documentation and versions with:

bundle exec thor docs:list

Download selected documentation by naming it, for example:

bundle exec thor docs:download html css

Update all installed documentation sets with:

bundle exec thor docs:download --installed

Download every documentation set currently available to the project with:

bundle exec thor docs:download --all

The project states that the manual installation has no update mechanism beyond pulling current code from the main branch and downloading the latest installed documentation:

git pull origin main
bundle exec thor docs:download --installed

These operations update different layers. The Git command updates application source, while the Thor command updates the documentation sets already installed. Test both the server and documentation behavior after an update.

Provide remote browser access with Localtonet

Complete this stage only after DevDocs works locally. Our client establishes an outbound connection to a Localtonet relay server, so the workflow does not require inbound router port forwarding, firewall changes, VPN setup, or a public IP address. An HTTP tunnel points to the local DevDocs IP address and port, then provides a public HTTPS URL while the selected client is connected and the tunnel is running.

This is standard HTTP tunneling, not VPN functionality. Localtonet VPN Manager is our separate private mesh VPN feature. For a browser application with a known local HTTP endpoint, an HTTP tunnel is the direct fit.

For the current interface and exact field presentation, consult our Localtonet HTTP tunnel documentation. Custom-domain DNS requirements can change and are not established by the evidence supplied for this article, so check the current documentation before configuring DNS.

Security and exposure considerations

A private local service and a publicly reachable URL have different risk profiles. Before starting the tunnel, decide who should be able to use the endpoint and whether DevDocs itself provides the access controls required by your environment. The supplied DevDocs evidence does not document built-in user authentication for this deployment, so we should not claim that the application protects the public endpoint with accounts, passwords, roles, or authorization.

If the application does not enforce the controls you need, do not assume that an unguessable URL is sufficient protection. Apply an appropriate access-control layer supported by your current architecture, limit exposure to the necessary period, and follow least-privilege policies. Exact Localtonet authentication or restriction options are not established in the supplied context and may vary by current product capability or plan, so verify the dashboard and documentation rather than relying on an unsupported claim.

Troubleshooting the complete workflow

The container name is already in use

Docker requires container names to be unique. Inspect the existing object:

docker ps -a --filter name=devdocs

If it is the intended DevDocs container, start it rather than creating another one:

docker start devdocs

Remove it only after confirming that replacement is appropriate:

docker rm devdocs

A running container must be stopped before ordinary removal.

Docker reports that port 9292 is already allocated

Inspect running containers with docker ps and identify any existing publication of port 9292. A non-Docker process can also own the port. Stop or reconfigure the conflicting service, then rerun the documented DevDocs command. Avoid changing several variables at once, since that makes later Localtonet target configuration harder to verify.

The container exits immediately

docker ps -a --filter name=devdocs
docker logs devdocs

Read the first relevant error rather than repeatedly restarting the container. If an image download was incomplete or the current image behaves unexpectedly, pull it again and recreate the container only after understanding that container removal is appropriate for your deployment.

The browser cannot open localhost:9292

Confirm the container is running and the port is published. Make sure the browser is running on the Docker host when using localhost. From a different computer, localhost refers to that other computer, not the DevDocs host. Resolve local addressing and firewall behavior before adding a tunnel.

The page loads but the interface does not work correctly

Test with a browser version inside the project's supported baseline. Check browser developer tools for failed requests, disable interfering extensions for a test, and review the container logs. Because DevDocs relies substantially on client-side JavaScript, a returned HTML page does not by itself establish that the application is fully functional.

The public URL returns an error

Work through the chain in order:

1. Open http://localhost:9292 on the DevDocs host.
2. Confirm the devdocs container is running.
3. Confirm the Localtonet client device is connected.
4. Confirm the HTTP tunnel is started rather than merely created.
5. Confirm its local target is the reachable DevDocs address and port 9292.
6. Test the assigned public URL again from a separate browser or network.

If our client runs on another machine, 127.0.0.1 points back to the client machine, not to the Docker host. In that topology, the tunnel target must be an address through which the client device can actually reach DevDocs. Verify that private network path directly before changing tunnel settings.

Local access works after an update, but expected documentation is missing

Container and manual deployments update differently. For manual installations, use bundle exec thor docs:list to inspect available sets and bundle exec thor docs:download --installed to update installed documentation. The Docker image workflow depends on the contents of the image being run. Confirm that you replaced the old container after pulling the newer image, since pulling an image alone does not alter an existing container.

Frequently asked questions