Installation guide
Access rights, tools, configurations etc. Admin rights required.
1. Silverfin access
Remote template development on Silverfin relies on the API capabilities of the platform. That means you'll need the necessary access rights to send and receive template information between the remote Silverfin platform and your local machine.
For Silverfin employees, you can find the credentials in our shared 1Password vault. (BSO Team CLI)
If your firm doesn't have API credentials yet:
- Contact your Customer Success Manager and let them know you want to start using Silverfin's API.
- We will draft an API agreement for your organisation to sign
- Once signed, our integration engineers will contact you to ask what you want to use the API for.
- You'll need the following scopes:
administration:read
administration:write
financials:read
financials:write
workflows:read
If you already have API credentials but forgot to save them, or when you don't have the necessary scopes:
- You can contact [email protected] for an adjustment to the scopes
2. Tools to install
You will need to install or configure the following on your machine to use the liquid toolchain to the fullest. A link to the official installation instructions has been provided for each item below.
Good to know
Commands in this guide are provided for Mac. The steps on Windows or Linux should be the same, but the installation process might look a bit different. Apart from our own CLI, the tools listed here are commonly used and you should be able to find help online if you need it.
If you are already using Git, skip this step.
git --version
- Create an account on GitHub
- Once you have an account, the admin in your organisation can add you to the relevant repositories.
We use the GitHub CLI to upload our SSH keys (see GIT config below) to GitHub.
- First, install the Homebrew package manager; you will need Homebrew to install the other packages (Mac/Linux only)
- The installer will ask for the admin password of your machine; press Enter once you have entered it to confirm the installation
- Note that the installation can take a little while
- During installation, you may receive the following warning: ... is not in your PATH
- Resolve by running the following commands:
- During installation, you may receive the following warning: ... is not in your PATH
echo 'eval "$(/opt/homebrew/bin/brew shellenv)"' >> /Users/changethistoyourusername/.zprofile
eval "$(/opt/homebrew/bin/brew shellenv)"
- Next, test if Homebrew was installed correctly, then use the Homebrew CLI to install the GitHub CLI:
brew -v
brew install gh
- To update the GitHub CLI, run the following Homebrew command:
brew upgrade gh
Check if already installed by running the command below, otherwise install Node.js from the official website.
node --version
Once Node.js is installed, install the Silverfin CLI. The Silverfin command line tool will be essential when developing Silverfin templates.
npm install -g https://github.com/silverfin/silverfin-cli.git
This is our recommended code editor. Make sure the app is installed in the "Applications" folder if you are using a Mac.
- Install code command
- Open the command palette in VSCode by pressing
CMD + SHIFT + P
- Type
install code
orshell command
- Choose the option
Shell Command: install βcodeβ command in PATH
If you receive an error message, first try running uninstall code
and then reinstalling code
- Recommended extensions (non-exhaustive)
- The best extension is, naturally, the Silverfin Development Toolkit
- Auto Close Tag
- ESLint
- Github Pull Requests
- Git Graph
- GitLens
- indent-rainbow
- YAML
- HTML CSS Support
While the use of regular extensions already adds great value to your template development, if you wish, you can also explore AI tools to take it to the next level. A note of caution: The Silverfin Templating Language (our take on Liquid) is not as common as other languages. As such, most AI tools are not trained specifically for our coding language. Nevertheless, we have found that there is value in trying out the following:
- GitHub Copilot & GitHub Copilot Chat (subscription needed)
- Cody AI (free limited version available)
3. GIT configuration
If this is your first time using Git, please follow the setup process below:
- Link Git on your local machine to your remote Github account
git config --global user.name "Your Name"
git config --global user.email "[email protected]"
- Set VSCode as your default editor (recommended)
git config --global core.editor code
- Verify your config is setup correctly. Additionally, you can also check where your local Git configurations are stored (optional)
git config --list
git config --list --show-origin
3.2 Set up SSH Keys
SSH Keys is the preferred method to authenticate your local machine with the remote repositories on GitHub. When pushing updates from your local repository to a remote repository, or when fetching code from a remote branch etc. you'll use the SSH Key to authenticate the transfer.
SSH Keys on Mac
- Navigate to the ssh keys folder
cd ~/.ssh
OR create the folder if it does not exist yet
mkdir ~/.ssh && cd ~/.ssh
- Generate the SSH key with the command below, adding the email address associated with your GitHub account (
-t ed22519
is the algorithm used to generated the key):
ssh-keygen -t ed25519 -C "[email protected]"
- After entering the command:
- The system will ask you for a file name, but you can leave this blank and press Enter
- By default the system will use
id_rsa
orid_ed25519
- By default the system will use
- Now you need to set a password. Be aware that:
- You cannot recover this password. If you lose it, you will need to generate a new SSH Key
- You will need to enter this password a lot.
- The terminal does not give visual feedback when you're typing a password. Type the password blindly and press Enter when you're done.
- The system will ask you for a file name, but you can leave this blank and press Enter
SSH Keys on Windows
- Generate the SSH key with the following command:
ssh-keygen -t ed25519 -C "[email protected]"
Same remarks apply as when setting up the password on a Mac. (see above)
- Add the SSH Key to the SSH-Agent
Use Windows Powershell (run as admin) to start the SSH-Agent.
Get-Service ssh-agent | Set-Service -StartupType Automatic
Start-Service ssh-agent
To check if the service started correctly, you can run the following:
Get-Service ssh-agent
- Configure Git to use the windows SSH-Agent
git config --global core.sshCommand C:/Windows/System32/OpenSSH/ssh.exe
3.3 Add SSH Key to GitHub account
Authenticate your GitHub account with the terminal (or command prompt etc) and upload the SSH Key you just created.
gh auth login
Help
You can run the
gh help
command to see a list of possible commands for the Github CLI.The same works for the Silverfin CLI:
silverfin --help
will return a list of commands to run.
Next, you need to answer a few prompts.
What account do you want to log into?
GitHub.com
What is your preferred protocol for Git operations?
SSH
Upload your SSH public key to your GitHub account?
(You should automatically have a proposed path to your generated SSH key)
/Users/username/.ssh/id_rsa.pub
How would you like to authenticate GitHub CLI?
Login with a web browser
Copy the one time code that is shown in your terminal first.
Now you can press any key inside the terminal and a browser window will open for you to login to your GitHub account.
Once you have logged in, you will receive a success message in the terminal. It should resemble the below:
β Authentication complete.
- gh config set -h github.com git_protocol ssh
β Configured git protocol
β Uploaded the SSH key to your GitHub account: /Users/usersname/.ssh/id_rsa.pub
β Logged in as GitHubUsername
To verify you are logged in to Github, run the following command:
gh auth status
4. Silverfin API configuration
You can configure the API credentials you received from Silverfin either with the code
command or open the config file directly and add them there.
sudo code ~/.zshrc
OR
sudo nano ~/.zshrc
Making and saving changes to the file with nano requires specific key combinations.
Save changes with control(^) + X
Confirm changes with y
Finally, hit enter
- When asked for a password, provide the password you use to login to your machine.
- You will receive a text document where you can enter the client ID and the client secret.
Enter the credentials you received from Silverfin.
export SF_API_CLIENT_ID="..."
export SF_API_SECRET="..."
- You can always test if the ID and SECRET have been stored correctly using the
echo
command.
echo $SF_API_CLIENT_ID
echo $SF_API_SECRET
These commands should return the strings you had saved.
If that does not work, try opening the file directly:
source ~/.zshrc
Updated 21 days ago