top of page

Istio Documentation - Local Build and Deploy


Istio is the most popular service mesh in the industry today. It is backed by a comprehensive documentation hosted at https://istio.io/latest/docs/

Like any open source project, Istio's documentation relies heavily on the contributions from the community. If you are passionate about documentation and would like to make a contribution, the first step is to set up the documentation site locally. In this article, we will learn the basic steps to achieve this.


Prerequisites


Local Setup

Fork the repository

Create a fork of the istio/istio.io repository


Clone the fork

Use the url of your forked repo

Create a branch

'issue-10' has been used as an example for the branch name
// Navigate to the project directory
cd istio.io
git checkout -b issue-10

Deploy the website locally

Istio provides a Docker image with all the tools needed, including Hugo which is the site generator. To build and publish the website locally within the docker container, execute the command below:

make serve
In case you receive an error stating "Failed to read Git log: fatal: detected dubious ownership in repository at '/work'", execute the below command locally and then run the make serve command again.
git config --global --add safe.directory /work

Once the website builds successfully, you should see the following message:

Built in 18037 ms
Environment: "development"
Serving pages from disk
Web Server is available at http://localhost:1313/latest/ (bind address 0.0.0.0)

Access the URL http://localhost:1313/latest/ from within a browser. The Istio documentation is now available to you locally.


Contribute changes

The documentation for the English language is available at the following path:

/content/en/docs

Navigate to the .md file you need to edit. Make the appropriate changes and save the file. Saving the changes automatically triggers a redeployment of the site. The browser refreshes automatically and this enables you to immediately validate your changes locally.

Once you are satisfied with your changes, perform the following steps:

Commit the changes to your local branch:

  git add <file paths>
  git commit -m "Fixed issue 10"

Push the changes to a branch on your fork:

git push origin issue-10

Raise a pull request from your branch to the istio.io master branch

After you raise a pull request, wait for a maintainer to review the changes. In case of any review comments, incorporate the changes and push a new commit.


Conclusion

Hope this article helps in getting you started on your journey to contribute to Istio documentation. In case of any issues, please post a reply and I will try to assist.

22 views

Recent Posts

See All

Comments

Rated 0 out of 5 stars.
No ratings yet

Add a rating
bottom of page