Creating Documentation

MKDocs ContainerAsset

The Client Documentation should be created based on Cluster/containerAssets/mkDocs/ in the Snippets Library. This is created as part of the Client Jira setup.

It should he hosted on the client's Jira container at /var/www/vhosts/mkdocs

For Containers missing the mkDocs asset

Because some Jira containers were set up before the mkDocs process was added, they'll need it adding retroactively.

  1. SSH to the cluster machine: ssh cluster2
  2. Run the omitted script:
    1
    /opt/Projects/snippets-edmondscommerce/Cluster/shellscripts/cluster/setupPublicFacingContainers/setupClientJira/_04_docs.bash <clientname>
    

Creating client docs bitbucket repo

Login as client to bitbucket.org and follow this create repo link Make it private repository and give it a name of client-docs.

Note

Don't forget to give edmondscommerce user acccess in the bitbucket by going your client-docs repo Settings page -> User and group access -> enter username edmondscommerce and give Admin permission.

Setting up the Post Receive Hook

To create a post receive hook for pushing to BitBucket and also to trigger a handbook build, you should locate the bare repo folder in gitBareRepos, in there is a folder called hooks

Before we can add in the handbook build, you need to make sure that the ssh key for gitBare has been copied into the mkdocs container. Run the following command and Change "CONTAINER_IP" with the IP address of the container that has the client docs on it (usually the Jira container). You can ssh into the container with sshContainer "container_name" .

1
ssh-copy-id CONTAINER_IP -p9516

Note

If you are doing this for a specific client handbook you will need to find the repo and then edit the post-receive file within the client repo itself on the gitBareRepos container.

In that folder we need a file called post-receive. It needs to have the correct permissions so to do this quickly you can run the following 2 commands touch post-receive which creates the file and then chmod 755 to change the permissions. To edit the file enter the following command vim post-receive which the file needs to have content like this:

1
2
3
4
5
6
7
#!/usr/bin/env bash

echo "Kicking off a backgrounded bitbucket sync and handbook build..."

bash /home/ec/post-receive-hooks/bitbucket-sync.bash "git@bitbucket.org:SLUG/HERE.git"

bash /home/ec/post-receive-hooks/handbook-build.bash "CONTAINER_IP_HERE"

The container IP is for the container that is hosting the client docs.

Note

To get the "slug/here" part of the 1st command, you will need to go onto bitbucket and get it. You can do this by looking at the "I have an existing project" drop down on a new repo or next to SSH on the overview page. To get the "CONTAINER_IP_HERE" All you need to do for this is ssh into the the required container and use one of the following commands

ip a or hostname -i

Once you have it all working, if you want it to be backgrounded so you get your prompt back as quickly as possible, you can set the hook to be this:

1
2
3
4
5
echo "Kicking off a backgrounded bitbucket sync and handbook build..."

nohup bash /home/ec/post-receive-hooks/bitbucket-sync.bash "git@bitbucket.org:SLUG/HERE.git" &> /dev/null &

nohup bash /home/ec/post-receive-hooks/handbook-build.bash "CONTAINER_IP_HERE" &> /dev/null &