practiv_

Set up tools

Get your environment up and running fast

Objective

This is day zero. Let’s get you up and running fast with the tools you need. We are big fans of open source tooling and avoid vendor lock in wherever possible.

Consistent environments save time

Having your local environments consistent across machines and build/run environments (CI, UAT or PROD) behave as consistently as possible makes it easier to understand the build process and work with other team members.

🍎
If development environments are consistent, any team member can assist each other and contribute to the ideal environment set up

What we are going to need

General dev tools:

  • Mac/Linux Terminal (MacOS/Linux)
  • Git Bash for Windows (Windows)
    • Windows hasn’t been known to provide a shell that has bash compatibility. To fill this gap this we recommend that you use the default shell provided with git, git bash.
    • Please download git for windows within your browser and run through the installation process.
  • Docker for Desktop (MacOS/Windows)
  • An IDE of choice (VSCode, IntelliJ, Notepad++ if you’re an anarchist, etc.)

Package managers to install software to your environment:

Access (and credentials) for your source and binary repositories

  • Either GitHub or GitHub Enterprise - repository server for source code and supporting functionality
  • Nexus - repository server for binary artifacts

Let’s get started.

Package management

We use package management to bootstrap your workstation and install the tools you will require to setup your development environment.

This continues to establish a consistent environment across all workstations. Once installed, a command like brew install gpg or choco install gpg will ensure that a software package is deployed to your workstation.

Common tools

Now we have standardised terminal and package management layers installed, we move onto installing common build and workspace tooling.

Some tooling is optional —  but we strongly recommend you start with a consistent local environment, and continue with that assumption thereafter.

Let’s install

MacOS / Linux

Run the following brew commands

brew tap install branchout
brew install git gpg branchout openjdk@17 maven gradle node@16 gh kubernetes-cli skaffold
brew cask install docker gpg-suite

On Apple Silicon, you need to ensure that Docker uses x86 images, by setting the default platform.

If you use zsh then

echo "DOCKER_DEFAULT_PLATFORM=linux/amd64" >> ~/.zshrc
source ~/.zshrc

for bash

echo "DOCKER_DEFAULT_PLATFORM=linux/amd64" >> ~/.bashrc
source ~/.bashrc

Windows

Firstly we install all the tools that have chocolatey packages:

From an Administrator Powershell:

choco install gpg4win openjdk17 maven node-lts yarn gh kubernetes-cli skaffold -y
choco install docker-desktop

Next, open a bash shell in your terminal program and install branchout.

cd ~/
git clone https://github.com/Branchout/branchout bin

Git credentials

You’ll need access to source repositories, please contact your git administrator. If that’s Practiv, email support@practiv.com and we’ll arrange access for you.

To manage our projected monorepo approach to software development, we open-sourced a local tool called Branchout that helps you manage multiple repositories in a single project easily. This tool is optional, but recommended.

Example using GH CLI
❯ gh auth login --hostname git.practiv.io
    - Logging into git.practiv.io
    # there are two possible ways to authenticate, "Login with a web browser" is the most straight forward
    ? How would you like to authenticate? Login with a web browser
    - Press Enter to open git.practiv.io in your browser...
    ✓ Authentication complete. Press Enter to continue...
    # git can be utilised over ssh or https, your organisation uses "ssh"
    ? Choose default git protocol ssh
    - gh config set -h git.practiv.io git_protocol ssh
    ✓ Configured git protocol
    ✓ Logged in as github-user
SSH access

If SSH access is preffered. Generate a new SSH key and upload it to GitHub.

Instructions can be found here.

Git defaults

Every commit that you make to git needs to have your user metadata associated with it. It’s straightforward to set your git user details globally.

git config --global user.name "First Last"
git config --global user.email "user.name@domain.com"

Here’s a few good citizen changes.

git config --global pull.rebase true
git config --global alias.nuke 'push --force-with-lease'
git config --global --replace-all core.pager "less -F -X"
git config --global alias.graph 'log --graph --all --decorate'

git config --global core.excludesfile ~/.gitignore_global

Having an excludes file is a good idea, as it allows you to ignore files that you don’t want to commit to git.

Your project

From here, we start using terms that we want you familiar with, so we’ll explain them up front.

A project — is the collection of repositories (detailed in a manifest) that make up your project including libraries, deployables and environments.

Control repository — we define a root git repository that defines your project. Generally your control repository and project have the same name. e.g. the root of Practiv’s own projects is called practiv.

Project settings — are the collection of properties (detailed in a settings file) that point to resources required during the build.

Artifact repositories — are your maven, npm and docker registries

Troubleshooting

Brew - proxy not configured

❯ brew install application
Error: No available formula with the name "application"
==> Searching for a previously deleted formula (in the last month)...
Error: No previously deleted formula found.
==> Searching for similarly named formulae...
Error: No similarly named formulae found.
==> Searching taps...
==> Searching taps on GitHub...
Warning: Error searching on GitHub: curl failed!
% Total    % Received % Xferd  Average Speed   Time    Time     Time  Current
                                    Dload  Upload   Total   Spent    Left  Speed
    0     0    0     0    0     0      0      0 --:--:-- --:--:-- --:--:--     0
    Warning: Transient problem: timeout Will retry in 1 seconds. 3 retries left.
    0     0    0     0    0     0      0      0 --:--:-- --:--:-- --:--:--     0
    Warning: Transient problem: timeout Will retry in 2 seconds. 2 retries left.
    0     0    0     0    0     0      0      0 --:--:-- --:--:-- --:--:--     0
    Warning: Transient problem: timeout Will retry in 4 seconds. 1 retries left.
    0     0    0     0    0     0      0      0 --:--:-- --:--:-- --:--:--     0
    curl: (6) Could not resolve host: api.github.com

You will need to re-apply your proxy settings.

brew - vpn not connected

❯ brew install node@12
==> Downloading https://homebrew.bintray.com/bottles/node%4012-12.18.4.catalina.bottle.tar.gz
Warning: Transient problem: timeout Will retry in 1 seconds. 3 retries left.
Warning: Transient problem: timeout Will retry in 2 seconds. 2 retries left.
Warning: Transient problem: timeout Will retry in 4 seconds. 1 retries left.
##O=#  #
curl: (5) Could not resolve proxy: proxy-a.orgname.com
Error: Failed to download resource "node@12"
Download failed: https://homebrew.bintray.com/bottles/node%4012-12.18.4.catalina.bottle.tar.gz
Warning: Bottle installation failed: building from source.
==> Downloading https://nodejs.org/dist/v12.18.4/node-v12.18.4.tar.gz
Warning: Transient problem: timeout Will retry in 1 seconds. 3 retries left.
Warning: Transient problem: timeout Will retry in 2 seconds. 2 retries left.
Warning: Transient problem: timeout Will retry in 4 seconds. 1 retries left.
##O=#  #
curl: (5) Could not resolve proxy: proxy-a.orgname.com
Error: Failed to download resource "node@12"
Download failed: https://nodejs.org/dist/v12.18.4/node-v12.18.4.tar.gz

Preferred: reconnect to your organisation’s protected network so that you have connectivity to your proxy servers.

Alternate: remove your proxy server configuration

brew - proxy not configured

❯ /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install.sh)"

curl: (6) Could not resolve host: raw.githubusercontent.com

❯ /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install.sh)"

curl: (6) Could not resolve host: raw.githubusercontent.com

At this point you may need to re-apply proxy settings.

brew - password request

❯ /bin/bah -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install.sh)"

# this password is your local machine password for sudo access
Password: *
==> This script will install:
...

You will need to be an admin on your workstation

Chocolatey - not running in elevated shell

❯ choco install gpg
Chocolatey v0.10.15
Chocolatey detected you are not running from an elevated command shell
    (cmd/powershell).
    You may experience errors - many functions/packages
    require admin rights. Only advanced users should run choco w/out an
    elevated shell. When you open the command shell, you should ensure
    that you do so with "Run as Administrator" selected. If you are
    attempting to use Chocolatey in a non-administrator setting, you
    must select a different location other than the default install
    location. See
    https://chocolatey.org/install#non-administrative-install for details.
    Do you want to continue?([Y]es/[N]o):

Always run choco from an administrator shell. Right click PowerShell -> Run as Administrator.

Proxy not configured

> branchout init https://git.practiv.io/Practiv/Practiv.git
Cloning into 'Practiv'...
fatal: unable to access 'https://git.practiv.io:Practiv/Practiv.git':
        Could not resolve host: git.practiv.io
Failed to clone https://git.practiv.io:Practiv/Practiv.git

branchout-init [git-url] [relocation]

You will need to re-apply your proxy settings

Prologue →