Blog

Centralized static documentation with Arcade

2019-09-29

There are a number of documentation services out there which offer private hosting. Readthedocs.com, the commercial counterpart to readthedocs.org, offers private documentation hosting for sphinx documentation. Hex.pm, the package management system for Elixir also offers private documentation hosting for hex packages. Other commonly suggested solutions are to host documentation on S3 and restrict by IP address with a bucket policy.

Image by cocoparisienne from Pixabay

For organizations that have package ecosystems in multiple languages, they’d have to either settle for using a solution like S3 with IP whitelisting, or host their own servers and authorize via IP or a home-rolled authorization solution. Arcade aims to provide a basic solution to this problem.

Arcade is a very basic webserver, built in Go using the gin web framework, so it’s lightweight and lightning-fast. It provides simple authentication using basic auth, and hosts files locally using gin’s StaticFS filesystem handler. It’s available on dockerhub as a Docker image, and can be pulled and set up locally very quickly:

docker pull crflynn/arcade
docker run -p 6060:6060 -it crflynn/arcade

There are a few environment variables which can be overridden to change the authentication, port, or disk location for persisting docs. These can be overridden with docker run. Shown below are the default values.

docker run -p 6060:6060 \
    -e ARCADE_PORT='6060' \
    -e ARCADE_DOCROOT='/tmp/docs' \
    -e ARCADE_USERNAME='admin' \
    -e ARCADE_PASSWORD='password' \
    -it crflynn/arcade

It is also beneficial to run this service with persistent disk, using something like a PersistentVolume in Kubernetes or bind mounts when running docker on a VM like EC2.

The API provides basic functionality for pushing and deleting static documentation to the host. Suppose we are building Python documentation using Sphinx. After building, navigate to the html folder, zip the contents and then submit a PUT request to the webservice. This hosts the documentation at the path specified:

# Navigate into the docs build directory (where index.html is).
# This will differ depending on language
# but the point is that we want the built static documentation.
# The example here uses the sphinx build dir for html
cd docs/_build/html
# create a tar file of the contents excluding the top folder
tar -czf ../myproject.tar.gz .
cd ..
curl -u username:password \
    -X PUT 'http://localhost:6060/docs/myproject/latest' \
    --upload-file myproject.tar.gz
curl -u username:password \
    -X PUT 'http://localhost:6060/docs/myproject/v1.2.3' \
    --upload-file myproject.tar.gz

To view the uploaded documentation, navigate to http://localhost:6060, and provide the username and password to authenticate. You should see the project/version routing provided by the StaticFS handler. You should see the documentation as the paths in which you PUT them earlier, e.g. http://localhost:6060/docs/myproject/latest.

To delete documentation, send an authenticated DELETE request to the same path.

# delete a single version
curl -u username:password \
    -X DELETE 'http://localhost:6060/docs/myproject/v1.2.3'
# delete an entire project
curl -u username:password \
    -X DELETE 'http://localhost:6060/docs/myproject'

flynn.gg

Christopher Flynn

Blog

Centralized static documentation with Arcade

Further reading

Arcade

Hosting

Documentation