Installing cgcam

The cgcam source is stored in a private repository on github. Only authorized users will have access to the repository and thus the git clone commands given below will fail if you have not been granted access.

CGCAM can be installed using either https or ssh protocol but, in either case, you will need to set up some authentication information on github first.

Using https

Github recommends https protocol. While this method is relatively simple, it does require having github generate a "personal access token" that will be used in lieu of a password when performing git command line operations that access github. Follow the instructions here https://docs.github.com/en/github/authenticating-to-github/keeping-your-account-and-data-secure/creating-a-personal-access-token to generate the token. It is sufficient to check only the 'repo' box when setting the scope for the token. Once the token is generated, you can copy it into the paste buffer and then save it to your keychain. Git can also store it in its own keychain via the command

git config --global credential.helper store

The --global option will make your stored credentials available to projects other than cgcam. You can also replace 'store' with 'cache' to have the credentials stored for specified period of time (the default being 15 minutes). The 'store' directive used above will make the credentials available permanently.

If you would like to have git store the token, issue the above command before you issue the clone command listed below. Note that you should be able to hit the copy button to the right of the lines above to have them added to your clipboard, at which point you can paste them onto the command line. The same is true for other commands listed in the documentation.

To actually clone the repository, issue

cd $HOME;
git clone --recurse-submodules https://github.com/MURI-Turbulence/cgcam.git

You will then be prompted for your github username and password. Using the paste buffer, paste your freshly-generated personal access token in at the password prompt. If you used the credential.helper to store your access token, subsequent git operations that access github will succeed without the username/password dialog.

Using ssh

While the https method is fairly simple, it does have a few disadvantages. If you loose track of your personal access token, you will need to generate a new one as github will not reveal previously-generated values. In addition, github recommends that you set an expiration date not to exceed 90 days when generating tokens. Thus tokens will need to be regenerated periodically and keychains updated on all systems where you have the code deployed. The ssh method avoids these problems through the use of permanent RSA keys. Follow the instructions here https://docs.github.com/en/github/authenticating-to-github/connecting-to-github-with-ssh/about-ssh to set up RSA keys.

As will be evident below, cgcam relies on the config submodule and this element will be installed automatically when the --recurse submodules option is passed to the git clone command. The configuration for this step requires that an authentication method be chosen in advance and the https method was chosen. This presents a conflict for a clone under ssh protocol since the main cgcam repository will be cloned using ssh, but the method will switch to https when working on the config submodule. The workaround is to instruct git to always use ssh. Do this by issuing

git config --global url.ssh://git@github.com/.insteadOf https://github.com/

The --global instructs git to always use ssh, even for projects other than cgcam. You can omit this option to make the change specific to just cgcam.

Once your keys are registered at github and you have instructed git to always use ssh, you can clone the cgcam and the config submodule via

cd $HOME;
git clone --recurse-submodules [email protected]:MURI-Turbulence/cgcam.git

There is no need to use the credential.helper in combination with ssh since authentication is done via the RSA keys instead of via a password or token.

Final note

Note that the URL on the clone command is different for https and ssh protocols. This means that you can not mix the authentication method, as in adding RSA keys in an attempt to access a repository registered with a https URL. If you have a need to switch the authentication method, you will need to follow the steps here https://docs.github.com/en/get-started/getting-started-with-git/managing-remote-repositories to re-register the github repository URL.