Step-by-Step Guide for Deployment

Deploying the OpenTelemetry documentation in a production environment involves a series of steps primarily handled through a Makefile. Below are the detailed steps to achieve this.

Prerequisites

Ensure that the following tools are installed on your system:

• Node.js
• Make

1. Clone the Repository

Clone the OpenTelemetry documentation repository from its source. This can typically be done using:

git clone https://github.com/open-telemetry/opentelemetry.io.git
cd opentelemetry.io

2. Install Dependencies

Navigate to the project directory and run the following command to install all necessary dependencies:

npm install

3. Organize Files

make clean

This function, defined in the Makefile, cleans up previously built files to ensure you start with a fresh state.

4. Build the Documentation

After setting up the repository and installing dependencies, you can build the documentation using the default target in the Makefile. This is accessed with the following command:

make

5. Check Links

It’s essential to ensure all links within the documentation are valid before deployment. You can run the link checker available in the Makefile to verify this:

make check-links

This executes the check-links function, which scans the documentation for broken links.

6. Save Link Changes

If any modifications are necessary based on the link check, you can save the changes using:

make refcache-save

This will save the current state of the references and link checks in your repository.

7. Public Deployment

Once you have validated and saved your changes, you can prepare the site for production. Use the public target in the Makefile to perform this action:

make public

This command will generate a public version of the documentation that is ready to be deployed.

8. Deploy to Production

At this stage, you will need to deploy the generated files to your production server. This typically involves copying the files to a web server or using a Continuous Deployment/Continuous Integration (CD/CI) platform if available.

Example of using rsync to deploy:

rsync -avz ./public/ user@yourserver:/path/to/deployment/

Replace user, yourserver, and /path/to/deployment/ with your specific details.

9. Verify Deployment

After deployment, access the production URL to verify that the documentation is displayed correctly and functioning as expected.

Conclusion

Following these detailed steps ensures that the OpenTelemetry documentation is smoothly deployed and maintains its integrity throughout the process.

Sources: Makefile