Now follows the part where it gets more technical. There's a convention at Renuo for the directory structure of projects. In every project you'll find the following files:
- For setting up the project:
bin/setup - To run the tests:
bin/check - to run and try the application:
bin/run
There are some requirements which need to be met first that this works. The following steps are going to prepare your system for that.
If you are experienced you can choose your own setup, but we recommend that you follow our setup instructions.
::: danger Important Please read the following instructions carefully. If you don't follow them, you may run into problems.
You should also have installed all the software from the previous steps "Non-technical Setup". If you haven't, please do so now. :::
- Sudo: Coming from the Linux world, you're maybe used to the sudo command. On a Mac, you should seldom be required to use sudo.
- Step by step: Go through the guide page by page. Press the right arrow key to go to the next page. Please don’t skip parts of this guide and don’t start with the next part or command if you haven’t finished the previous one. In general, the commands are only guaranteed to work in the order of the guide and cannot be parallelized.
- Read and understand the command line outputs: The installer will tell you useful / necessary hints, which may require action. Additionally, this guide may be partly outdated soon, which makes it even more important to read the outputs of the installers.
- Discuss changes: Please extend or correct this guide if you think the information is missing, wrong or outdated. Discuss the changes you want to make here with at least one other person before you make them.
- Ask for help: If you have any questions, please ask for help. We are happy to help you.
Go to Developer
- Click on "Account", login with your Renuo AppleID
- Agree by checking boxes and submit
Create a Developer folder in your home directory: ~/Developer.
Your Mac should automatically recognise this folder and add a 🔨 icon.
You can now use this folder to clone all your GitHub projects.
::: danger Warning All System Updates must be installed before installing Xcode. Xcode is necessary for all the following steps. :::
- Download Xcode from the App Store
- Open Xcode and agree to license, then quit
While Xcode is installing, you can take a break and get a coffee ☕️.
We recommend you to use iTerm2 - macOS Terminal Replacement but you can freely choose your desired terminal application.
::: danger Warning Make sure you have installed Xcode and agreed to the license before installing Homebrew ― otherwise it will fail. :::
Homebrew is a very convenient package manager for Mac. Go to Brew and execute in the terminal what is written there (asks for sudo permissions). Afterwards run the following to keep your packages up-to-date:
brew updatebrew upgrade
This is a highly configurable console editor which can be expected to be present on every Renuo system.
brew install vim
In the following sections we need to create and edit a lot of files. We will use Vim for this. If you are not familiar with Vim, you can use Visual Studio Code for example.
Checkout VIM Shortcuts for a quick introduction.
Download and install Visual Studio Code.
Once installed, open the command palette (⇧⌘P) and type shell command to find the Shell Command: "Install 'code' command in PATH command".
Create a file
touch <filename>
Open a file
vim <filename>
or
code <filename>
Example
touch .gitconfig
code .gitconfig
## or
vim .gitconfigThis is an alternative shell to bash (Mac standard).
It has some interesting features, a big community and its mechanisms are used in a wide range of scripts at Renuo.
You don't have to install it, but be aware that all configuration steps
below which involve ~/.zshrc have to be customized to take into account the shell you're using.
There is already a version of zsh installed on your Mac, but it's probably old.
You can use homebrew to install a more recent one:
brew install zsh
Configure it as your login shell the following way:
- Go to System Preferences
- → Users & Groups
- → Right click to your user
- → Advanced Options
- → Change Login-Shell to "/opt/homebrew/bin/zsh" to use the Homebrew zsh. (the old native one would be: "/bin/zsh")
For zsh there are several plugin systems. One of them is antigen. It's very flexible and you can use repositories like oh-my-zsh with it.
brew install antigen
Do what it tells you to do and try out some plugins ZSH-Plugin Manager. For example you can put the following into your ~/.zshrc to use oh-my-zsh:
antigen use oh-my-zshantigen theme agnosterantigen apply
This is a distributed versioning control system widely used. It's our standard.
brew install git
You can configure nice shortcuts in your console with the antigen bundles git, git-extras, git-flow.
Put the following into your: ~/.gitconfig:
[user]
name = <YOUR-FULL-NAME>
email = <YOUR-EMAIL>@renuo.ch
[core]
excludesfile = /Users/<YOUR-NAME>/.gitignorePulling without specifying how to reconcile divergent branches is discouraged. You can squelch this message by running one of the following commands sometime before your next pull:
git config --global pull.rebase false # merge (the default strategy)
git config --global pull.rebase true # rebase
git config --global pull.ff only # fast-forward only (the recommended strategy)
This will be reflected in ~/.gitconfig.
Put the following into your: ~/.gitignore:
## Folder view configuration files
.DS_Store
Desktop.ini
.idea
*.iml
## Thumbnail cache files
._*
Thumbs.db
## Files that might appear on external disks
.Spotlight-V100
.TrashesGit Flow is a branching convention we use at Renuo. There is a tool which makes it more convenient to use:
brew install git-flow
This is a tool for public key crypto. There is also a tool called GPGSuite which has a GUI. You can use gpg to create your ssh key.
brew install gpg
An SSH key is a token which can be used to identify you and your machine. Everyone at our company has at least one. You can use this guide to create one:
Go to your GitHub settings and "Add a new SSH key". Use 1Password to generate an ED25519 SSH key.
SSH-Agent
Follow the instructions on 1Password to use the 1Password SSH-Agent. See also 1Password SSH Agent
Git Commit Signing
Setup signing your commits with 1Password. See also Git Commit Signing
asdf Manage multiple runtime versions with a single CLI tool:
brew install asdf
Put the following into your: ~/.zshrc:
. $(brew --prefix asdf)/libexec/asdf.sh
Now you can install ruby and node:
asdf plugin add rubyasdf plugin add nodejs
And then:
asdf install ruby latestasdf install nodejs latest
To add a global ruby add:
asdf global ruby latest
To support .ruby-version add this to your ~/.asdfrc
legacy_version_file = yes
See also Guide
Yarn is a package manager for node packages.
brew install yarn --ignore-dependencies
Postgres is the main database we use for our projects. Install it and configure it to be started automatically:
brew install postgresqlbrew services start postgresql
Redis is used for ActionCable in Rails 5.2 and other projects with Sidekiq. You can use homebrew to install it:
brew install redis
After the installation run through, you will get a command to start redis:
brew services restart redis
To add the Heroku CLI, please use the following command.
brew tap heroku/brew && brew install heroku
To add the Renuo CLI, please use the following command.
cd ~asdf global ruby latestgem install renuo-cli
See Guide
brew install shared-mime-infobrew install imagemagick
brew install mysqlbrew install zstd
brew install pdftk-java
Task: Add your public key to the Renuo public keys repository.
First, clone the Renuo public keys repository.
git clone [email protected]:renuo/ssh-public.renuo.ch.gitThen add your public key named <your-name>.pub. You can export your public key from 1Password.
For more information, see Share a public key.
Then commit and push your public key.
git checkout -b feature/add-<your-name>-public-key
git add <your-name>.pub
git commit -m "Add <your-name> public key"
git pushAfterward, create a pull request on the Renuo public keys repository. This will ensure that you have the correct permissions to push and correctly set up your SSH key. Please check if your commit is signed.
Now ask someone to review your pull request.
Congratulations! You have created your first pull request at Renuo.
::: info Tip If you cannot push to the repository, you may not have the correct permissions, or you have not set up your SSH key correctly. Check out the SSH Key Setup section. :::
To keep your system up-to-date, you should run the following commands regularly:
brew updatebrew upgradebrew cleanup
::: info Tip
If this fails, try to run brew doctor or brew tap --repair to fix the issue.
:::
Checkout the update script for a more convenient way to update your system.
Make sure you have mas (Mac App Store command line interface) installed. You can install it using Homebrew:
brew install mas
Then you can list all outdated apps:
mas outdated
And update them:
mas upgrade
To list all pending macOS updates, you can use the following command:
softwareupdate -l
Go to system preferences and install the updates.
You are now ready to start working with the Renuo stack.
One last thing to do is to verify that everything is working.
Now you should be able to clone any project from the Renuo GitHub and start up the website.
To verify this:
- Clone a project. e.g.: Gifcoins2
- Use:
bin/setup - Use:
bin/run
Open the website in Google Chrome and check if everything is working.