Skip to content

Commit d5565fd

Browse files
wsoyinkawsoyinka
committed
maintainer guide - README.md
1 parent e68028e commit d5565fd

1 file changed

Lines changed: 192 additions & 0 deletions

File tree

‎README.md‎

Lines changed: 192 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,195 @@
11
# docs.rockylinux.org
22

33
![Deployment:Production](https://github.com/rocky-linux/docs.rockylinux.org/actions/workflows/staging.yml/badge.svg)
4+
5+
## Overview
6+
7+
This repository is responsible for building and deploying the official Rocky Linux documentation site, hosted at [docs.rockylinux.org](https://docs.rockylinux.org). The site is built and deployed automatically via the [Vercel](https://vercel.com/) platform.
8+
9+
> [!IMPORTANT]
10+
> This repository contains the *build and deployment logic only*. It does not contain the documentation content itself.
11+
12+
## Content Source
13+
14+
All documentation content is sourced from the [rocky-linux/documentation](https://github.com/rocky-linux/documentation) GitHub repository. The build script in this repository clones the content repo during the Vercel deployment process.
15+
16+
## How the Build Process Works
17+
18+
The deployment process is orchestrated by Vercel, which executes a custom build script.
19+
20+
1. **Trigger:** A push to this repository's `main` branch triggers a new build on Vercel.
21+
2. **Build:** Vercel runs the `./scripts/vercel-build.sh` script, which uses [mkdocs](https://www.mkdocs.org/) and the [mike](https://github.com/jimporter/mike) plugin to build a versioned static HTML site.
22+
3. **Deploy:** The script places the final generated site into the `site/` directory, which Vercel then deploys to production.
23+
4. **URL Structure:** The site uses a "Root + Versioned" deployment strategy. The latest documentation (currently Rocky Linux 10) is served from the root URL (`/`), while all documentation versions remain accessible via versioned paths (e.g., `/8/`, `/9/`, `/latest/`).
24+
25+
## Key Files & Scripts
26+
27+
- `vercel.json`: Configures Vercel to use the custom build command and specifies the output directory (`site`).
28+
- `scripts/vercel-build.sh`: The primary script that orchestrates the entire build. It contains all the logic for cloning, versioning, and building the documentation.
29+
- `requirements.txt`: A standard Python file listing the dependencies required for the build, such as `mkdocs` and `mike`.
30+
- `mkdocs.yml`: The main configuration file for `mkdocs`. The build script manages which configuration is used for the build.
31+
32+
## Deep Dive: The `vercel-build.sh` Script
33+
34+
This script is the heart of the repository and is designed to run within the Vercel environment. For maintainers, understanding its structure is key.
35+
36+
#### Stage 1: Initialization
37+
The script begins by installing Python dependencies from `requirements.txt`. It also creates a small `mkdocs` executable wrapper script. This ensures that `mike` can find and use the correct `mkdocs` instance within the Vercel build environment's `PATH`.
38+
39+
#### Stage 2: The `build_version` Function
40+
This function is called for each documentation version that needs to be built. It:
41+
1. Clones a specific branch (e.g., `rocky-8`) from the `rocky-linux/documentation` repository.
42+
2. Crucially, it performs a full clone to preserve the entire git history. This is required for the `git-revision-date-localized-plugin` to accurately display when a page was last updated.
43+
3. It uses symlinks to make the cloned content available to `mike` while preserving the git context.
44+
45+
#### Stage 3: Building with `mike`
46+
After cloning a version, the script uses `mike deploy` to build the static HTML for that version. `mike` manages the versioning by committing the built site to a temporary `gh-pages` branch within the build environment. This process is repeated for all specified versions.
47+
48+
#### Stage 4: Site Extraction
49+
Once `mike` has built all versions into the `gh-pages` branch, the script extracts the complete static site into the `site/` directory using `git archive`. This directory is the final artifact that Vercel will deploy.
50+
51+
#### Stage 5: Root Deployment
52+
To ensure `docs.rockylinux.org` serves the latest documentation directly, the script performs a final step: it copies all content from the `site/latest/` directory to the root of the `site/` directory. It carefully preserves the `versions.json` file to ensure the version-switching dropdown menu continues to function correctly across the entire site.
53+
54+
## How to Maintain the Site
55+
56+
Maintenance typically involves modifying the build script to add, update, or remove documentation versions.
57+
58+
#### Adding a New Documentation Version
59+
1. Open `scripts/vercel-build.sh`.
60+
2. Find the section where `build_version` is called.
61+
3. Add a new line for the new version, specifying the version number and the corresponding branch name from the content repository. For example, to add Rocky Linux 11 from the `rocky-11` branch:
62+
```bash
63+
build_version "11" "rocky-11" "" ""
64+
```
65+
66+
#### Changing the Default Version
67+
The default version is the one aliased to `latest`.
68+
1. Open `scripts/vercel-build.sh`.
69+
2. Modify the `build_version` call that includes `"latest"` as the alias. For example, to make version 11 the new latest:
70+
```bash
71+
# Old
72+
build_version "10" "main" "latest" ""
73+
74+
# New
75+
build_version "11" "rocky-11" "latest" ""
76+
```
77+
3. The `mike set-default` command uses `latest`, so it does not need to be changed.
78+
79+
#### Removing an Old Version
80+
1. Open `scripts/vercel-build.sh`.
81+
2. Find the `build_version` call for the version you want to remove and delete or comment out the line.
82+
83+
## Managing Deployments on Vercel
84+
85+
Deployments are handled automatically by Vercel when commits are pushed to the `main` branch. However, maintainers can also manage deployments manually via the Vercel CLI or the web dashboard.
86+
87+
### Vercel CLI
88+
89+
For more direct control, the Vercel CLI is a powerful tool. It allows you to deploy, manage, and inspect your project from the command line.
90+
91+
#### 1. Installation
92+
First, install the Vercel CLI globally using `npm` (Node.js is required):
93+
```shell
94+
npm i -g vercel
95+
```
96+
97+
#### 2. Login
98+
Log in to your Vercel account. This will likely open a browser window for authentication.
99+
```shell
100+
vercel login
101+
```
102+
103+
#### 3. Linking the Project
104+
Before you can manage a project, you must link your local directory to the remote Vercel project. This is a crucial one-time step.
105+
106+
```shell
107+
# Clone the repository if you haven't already
108+
git clone https://github.com/rocky-linux/docs.rockylinux.org.git
109+
cd docs.rockylinux.org
110+
111+
# Link the project
112+
vercel link
113+
```
114+
The CLI will interactively guide you to select the correct Vercel scope (team) and project.
115+
116+
For non-interactive environments or to be explicit, you can use flags:
117+
```shell
118+
# Example of linking to a specific project within a specific scope (team)
119+
vercel link --scope=rocky-linux-scope --project=docs-rockylinux-org
120+
```
121+
> [!NOTE]
122+
> Replace `rocky-linux-scope` and `docs-rockylinux-org` with the actual scope and project names on Vercel.
123+
124+
#### 4. Triggering Manual Deployments
125+
You can trigger new builds and deployments directly from your local machine. This is useful for testing changes in a preview environment before merging to `main`.
126+
127+
- **Preview Deployment:** Create a unique preview deployment with its own URL. Vercel builds the project and provides a link to the result.
128+
```shell
129+
vercel
130+
```
131+
- **Production Deployment:** Push a new build to the official production domain (`docs.rockylinux.org`).
132+
```shell
133+
vercel --prod
134+
```
135+
> [!WARNING]
136+
> This command updates the live site. It should only be used when you are certain the build is stable.
137+
138+
#### 5. Inspecting Deployments & Logs
139+
- **List Projects:** To see all projects you have access to:
140+
```shell
141+
vercel project ls
142+
```
143+
- **List Deployments:** To see a list of recent deployments for the linked project:
144+
```shell
145+
vercel ls
146+
```
147+
- **View Logs:** To view the build or runtime logs for a specific deployment in real-time, use the deployment URL provided by the `vercel` or `vercel ls` commands:
148+
```shell
149+
vercel logs <deployment-url>
150+
```
151+
152+
#### 6. CLI Troubleshooting
153+
- **Authentication Issues:** If you get permission errors, run `vercel login` again to re-authenticate.
154+
- **Wrong Project/Scope:** If commands are failing or not showing the right information, you may be linked to the wrong project. Run `vercel link` again to re-link your local directory. You can check the current link status by inspecting the `.vercel` directory.
155+
- **Build Failures:** If a manual deployment with `vercel` fails, the command will output a URL to the build logs for you to inspect.
156+
157+
### Vercel Web UI
158+
159+
The [Vercel Dashboard](https://vercel.com/) provides a user-friendly web interface for project management. After logging in and selecting the project, you can perform several key actions:
160+
161+
- **Viewing Deployments:**
162+
1. Navigate to the project's dashboard.
163+
2. Click the **Deployments** tab.
164+
3. Here you will see a complete history of all deployments (both production and preview), along with their status, branch, and commit message.
165+
166+
- **Inspecting Logs:**
167+
1. From the **Deployments** list, click on a specific deployment.
168+
2. Select the **Build Logs** or **Functions** tab to view detailed logs. This is essential for diagnosing a failed build.
169+
170+
- **Promoting to Production:**
171+
You can manually promote a successful preview deployment to production without needing a new build.
172+
1. Find the desired preview deployment in the **Deployments** list.
173+
2. Click the overflow menu (three dots) on the right.
174+
3. Select **Promote to Production**.
175+
176+
- **Managing Domains and Settings:**
177+
- **Domains:** Use the **Settings -> Domains** tab to manage custom domains and subdomains.
178+
- **Environment Variables:** Use the **Settings -> Environment Variables** tab to add, edit, or remove any necessary variables for the build environment.
179+
180+
## Local Development & Testing
181+
182+
You can simulate the Vercel build process locally to test changes.
183+
1. Ensure you have Python 3 and `pip` installed.
184+
2. Install the required dependencies:
185+
```shell
186+
pip3 install -r requirements.txt
187+
```
188+
3. Run the build script:
189+
```shell
190+
./scripts/vercel-build.sh
191+
```
192+
4. The script will execute the full build process and place the output in the `site/` directory. You can inspect the contents or serve them locally with a simple web server to verify your changes.
193+
```shell
194+
python3 -m http.server --directory site
195+
```

0 commit comments

Comments
 (0)