Running the docs.rockylinux.org website locally for web development | Podman¶
This document walks through how to recreate and run a local copy of the entire docs.rockylinux.org website on your local machine. Running a local copy of the documentation website might be useful in the following scenarios:
- You are interested in learning about and contributing to the web development aspects of the docs.rockylinux.org website
- You are an author and you'd like to see how your documents will render/look on the docs website before contributing them
Create the content environment¶
-
Ensure that the prerequisites are satisfied. If not please skip to the "Setup the prerequisites" section and then return here.
-
Change the current working directory on your local system to a folder where you intend to do your writing. We will refer to this directory as
$ROCKYDOCS
in the rest of this guide. For our demo here,$ROCKYDOCS
points to$HOME/projects/rockydocs
on our demo system.Create
$ROCKYDOCS
if it doesn't already exist and change your working directory to$ROCKYDOCS
type:mkdir -p $HOME/projects/rockydocs export ROCKYDOCS=${HOME}/projects/rockydocs cd $ROCKYDOCS
-
Ensure you have
git
installed (dnf -y install git
). While in $ROCKYDOCS use git to clone the official Rocky Documentation content repo. Type:git clone https://github.com/rocky-linux/documentation.git
You will now have a
$ROCKYDOCS/documentation
folder. This folder is a git repository and under git's control. -
Also use
git
to clone the official docs.rockylinux.org repo. Type:git clone https://github.com/rocky-linux/docs.rockylinux.org.git
You will now have a $ROCKYDOCS/docs.rockylinux.org
folder. This folder is where you can experiment with your web development contributions.
Create and Start the RockyDocs web development environment¶
-
Ensure you have Podman up and running on your local machine (you can check with
systemctl
). Test by running:systemctl enable --now podman.socket
-
Create a new
docker-compose.yml
file with the following contents:version: '2' services: mkdocs: privileged: true image: rockylinux:9.1 ports: - 8001:8001 environment: PIP_NO_CACHE_DIR: "off" PIP_DISABLE_PIP_VERSION_CHECK: "on" volumes: - type: bind source: ./documentation target: /app/docs - type: bind source: ./docs.rockylinux.org target: /app/docs.rockylinux.org working_dir: /app command: bash -c "dnf install -y python3 pip git && \ ln -sfn /app/docs docs.rockylinux.org/docs && \ cd docs.rockylinux.org && \ git config --global user.name webmaster && \ git config --global user.email webmaster@rockylinux.org && \ curl -SL https://raw.githubusercontent.com/rocky-linux/documentation-test/main/docs/labs/mike-plugin-changes.patch -o mike-plugin-changes.patch && \ git apply --reverse --check mike-plugin-changes.patch && \ /usr/bin/pip3 install --no-cache-dir -r requirements.txt && \ /usr/local/bin/mike deploy -F mkdocs.yml 9.1 91alias && \ /usr/local/bin/mike set-default 9.1 && \ echo All done && \ /usr/local/bin/mike serve -F mkdocs.yml -a 0.0.0.0:8001"
Save the file with the file name
docker-compose.yml
in your $ROCKYDOCS working directory.You can also quickly download a copy of the docker-compose.yml file by running:
curl -SL https://raw.githubusercontent.com/rocky-linux/documentation-test/main/docs/labs/docker-compose-rockydocs.yml -o docker-compose.yml
-
Finally use docker-compose to bring up the service. Type:
docker-compose up
View the local docs.rockylinux.org website¶
If you have a firewall running on your Rocky Linux system, ensure that port 8001 is open. Type:
firewall-cmd --add-port=8001/tcp --permanent
firewall-cmd --reload
With the container up and running, you should now be able to point your web browser to the following URL to view your local copy of the site:
OR
Setup the prerequisites¶
Install and setup Podman and other tools by running:
sudo dnf -y install podman podman-docker git
sudo systemctl enable --now podman.socket
Install docker-compose and make it executable. Type:
curl -SL https://github.com/docker/compose/releases/download/v2.16.0/docker-compose-linux-x86_64 -o /usr/local/bin/docker-compose
chmod 755 /usr/local/bin/docker-compose
Fix permissions on docker socket. Type:
sudo chmod 666 /var/run/docker.sock
Notes¶
- The instructions in this guide are NOT a prerequisite for Rocky documentation authors or content contributors
- The entire environment runs in a Podman container and so you will need Podman properly setup on your local machine
- The container is built on top of the official Rocky Linux 9.1 docker image available here https://hub.docker.com/r/rockylinux/rockylinux
- The container keeps the documentation content separate from the web engine (mkdocs)
- The container starts a local web server listening on port 8001.
Author: Wale Soyinka
Contributors: Ganna Zhyrnova