Manual MacOS Setup

This guide will explain how to install Riptide under MacOS. If possible you may want to consider using the nix-darwin setup instead. It is more convenient and comes with more features out of the box (such as proxy autostart, which is otherwise not supported for macOS).

Installing Requirements

This guide assumes you want to run Riptide in the most common set-up using the Docker Engine. To use Riptide you need to have the following installed:

Python is available for Mac machines using package managers.

There is a good chance you already have Python installed. Try running python3 --version to check.

Installing Riptide

Riptide should always be installed in a dedicated Python virtual environment to avoid conflicts between system packages and Riptide.

Choose a directory you want to store the virtualenv at, create a new virtualenv for Riptide and activate it:

cd ~/virtualenvs  # This can be whereever you want
python3 -m venv riptide
source riptide/bin/activate # Activates the virtualenv

Then, to install all Riptide components and the Docker implementation run the following command:

pip3 install riptide-all

After this you will need to re-activate the virtualenv every time you want to use Riptide, or add the Riptide commands to the PATH:

# We asume ~/.local/bin is in the PATH and your virtualenv is at ~/virtualenvs. You can choose other directories if not.
ln -s ~/virtualenvs/riptide/bin/riptide ~/.local/bin
ln -s ~/virtualenvs/riptide/bin/riptide_proxy ~/.local/bin
ln -s ~/virtualenvs/riptide/bin/riptide_upgrade ~/.local/bin

You can test if Riptide is working:

Initializing the configuration

You will then need to initialize the Riptide configuration if this is the first time using Riptide. If you used Riptide before skip this step (this will otherwise reset your configuration):

riptide config-edit-user --factoryreset

Shell integration

Riptide adds some additional features to your shell, in order to automatically add project commands into your shell. Add the following lines to your .zshrc after any changes to PATH:

# Riptide shell integration
. riptide.hook.zsh
# Riptide code completion
eval "$(_RIPTIDE_COMPLETE=zsh_source riptide)"

If you use Bash, add this to your .bashrc after any changes to PATH:

# Riptide shell integration
. riptide.hook.bash
# Riptide code completion
eval "$(_RIPTIDE_COMPLETE=bash_source riptide)"

SSL Certificate

Finally you want to import the SSL certificate authority. This allows your browser to trust the Riptide proxy server. See Import the SSL certificate authority for more details.

Updating Riptide

To update Riptide, run:

riptide_upgrade

After this make sure to restart the Proxy server.

Configuring shared folders (Docker Desktop)

Docker Desktop for MacOS only allows the virtual machine running the Docker daemon limited access to your machine.

The default configuration is not enough to use Riptide. Please open the settings of Docker and navigate to the Shared Folders tab. Make sure the following entries are present:

  • /Users

  • /Volumes

  • /private

  • /tmp

  • /var/folders

  • /usr/local/lib/python3.7 (Or wherever else Python is installed!)

Known issues under MacOS

  • Due to emulation, Docker will generally run slower on macOS than on Linux. Consider using OrbStack, as it has been reported to be much faster than Docker Desktop. Additionally Riptide has some Performance optimizations enabled by default to increase performance.

  • Due to the performance optimization settings, it might happen that changes to files are not immediately visible on the host system or the running containers. Some files are not updated on the host system at all (see Performance optimizations).

Next steps

You are now ready to use Riptide. Head to the user documentation for more information on how to use it: