12ffd3e638
Why: Smoketests fail as they can not establish IPv6 connection to uvicorn backend server. https://github.com/vyos/vyos-1x/pull/2481 added a bunch of new smoketests. While debugging those failing, it was uncovered, that uvicorn only listens on IPv4 connections vyos@vyos# netstat -tulnp | grep 8080 (Not all processes could be identified, non-owned process info will not be shown, you would have to be root to see it all.) tcp 0 0 127.0.0.1:8080 0.0.0.0:* LISTEN - As the CLI already has an option to move the API communication from an IP to a UNIX domain socket, the best idea is to make this the default way of communication, as we never directly talk to the API server but rather use the NGINX reverse proxy.
Starting with VyOS 1.2 (crux) our documentation is hosted on ReadTheDocs at https://docs.vyos.io
Our old wiki with documentation from the VyOS 1.1.x and early 1.2.0 era can still be accessed via the Wayback Machine
Build
Versions
Our version follows the very same branching scheme as the VyOS source modules
itself. We maintain one documentation branch per VyOS release. The default
branch that contains the most recent VyOS documentation is called master
and matches the latest VyOS release which is 1.4 at the time.
All new documentation enhancements go to the master branch. If those changes
are beneficial for previous VyOS documentation versions they will be
cherry-picked to the appropriate branch(es).
Post-1.2.0 branches are named after constellations sorted by area from smallest to largest. There are 88 of them, here's the complete list.
- 1.2.x:
crux(Southern Cross) - 1.3.x:
equuleus(Little Horse) - 1.4.x:
sagitta(Arrow) - ...
Sphinx
Debian requires some extra steps for
installing sphinx, sphinx-autobuild, sphinx-notfound-page, sphinx-panels,
sphinx-rtd-theme, lxml, and myst-parser packages:
First ensure that Python 2 & Python 3 are installed and Python 3 is the default:
python --version
Alternatively, to make Python the default, revise the following line to point at the relevant 3.x version of the binary on your system:
sudo update-alternatives --install /usr/bin/python python /usr/bin/python3 0
Then install the sphinx group of packages:
sudo apt-get install python3-sphinx
Although almost everything uses Python 3, in order to install this specific package, make sure that pip points at the Python 2 version of the package manager:
python --version
Then run:
sudo pip install sphinx-autobuild sphinx-notfound-page sphinx-panels sphinx-rtd-theme lxml myst-parser
Do the following to build the HTML and start a web server:
- Run
make livehtmlinside thedocsfolder
Then, to view the live output:
- Browse to http://localhost:8000 Note: The changes you save to the sources are represented in the live HTML output automatically (and almost instantly) without the need to rebuild or refresh manually.
Docker
Using our Dockerfile you can create your own Docker container that is used to build a VyOS documentation.
Setup
You can either build the container on your own or directly fetch it prebuilt from Dockerhub. If you want to build it for yourself, use the following command.
$ docker build -t vyos/vyos-documentation docker
Building documentation
If the vyos/vyos-documentation container could not be found locally it will be
automatically fetched from Dockerhub.
$ docker run --rm -it -v "$(pwd)":/vyos -w /vyos/docs \
-e GOSU_UID=$(id -u) -e GOSU_GID=$(id -g) vyos/vyos-documentation make html
# sphinx autobuild
$ docker run --rm -it -p 8000:8000 -v "$(pwd)":/vyos -w /vyos/docs -e \
GOSU_UID=$(id -u) -e GOSU_GID=$(id -g) vyos/vyos-documentation make livehtml
Test the docs
To test all files, run:
$ docker run --rm -it -v "$(pwd)":/vyos -w /vyos/docs \
-e GOSU_UID=$(id -u) -e GOSU_GID=$(id -g) vyos/vyos-documentation vale .
to test a specific file (e.g. quick-start.rst)
$ docker run --rm -it -v "$(pwd)":/vyos -w /vyos/docs -e GOSU_UID=$(id -u) \
-e GOSU_GID=$(id -g) vyos/vyos-documentation vale quick-start.rst