Mac Phoenix Dev Setup

Setting up a development environment can be perceived as overwhelming, given the multitude of tools and configurations to take into account. However, in this post, I will guide you through each step to effortlessly install everything you need for a complete Phoenix Liveview development environment using the command line. You'll find a complete script at the end of this post, which consolidates all these steps for efficient setup and automation. The following are the distinct steps I have divided this script into:

  1. Install xCode command line tools
  2. Set Zsh as the default shell
  3. Install Oh My Zsh
  4. Install Homebrew
  5. Configure Oh My Zsh
  6. Install Code Editor and Database Client
  7. Install Languages
  8. Install Phoenix Project Generator

At the end I will guide you through using the script.

1. Install xCode command line tools

This step is required for every mac user regardless of the language you are going to be coding in.

xcode-select --install

2. Set Zsh as the default shell

Zsh, the default shell for macOS versions released after Catalina (older versions default to Bash), offers a more efficient and user-friendly experience when compared to Bash.

You can check which shell you are using with the command

echo $0

If Zsh isn't your default shell, you can switch to it with the following commands. Remember, you'll need to restart or re-login for the changes to take effect:

brew install zsh
chsh -s /bin/zsh

3. Install Oh my Zsh

Zsh, the default shell for macOS, can be transformed into a powerhouse with Oh My Zsh, a delightful open-source framework for managing Zsh configurations, below is the command to install it:

curl -fsSL <https://raw.githubusercontent.com/robbyrussell/oh-my-zsh/master/tools/install.sh>

4. Install Homebrew

Homebrew is a cornerstone of the macOS command-line interface, acting as a package manager to easily install and manage software. In my opinion, trying to operate without it is like shooting yourself in both feet. Lets install it now:

curl -fsSL <https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh>

5. Configure Oh my Zsh and extensions

Extensions

Next we are going to enhance your shell with Zsh extensions:

brew install zsh-autosuggestions 
echo 'source $(brew --prefix)/share/zsh-autosuggestions/zsh-autosuggestions.zsh' >> ~/.zshrc

Now that your extensions are installed, restart your shell application or source your configuration with omz reload and the extension should be installed and ready for use.

Aliases

Ever find yourself typing the same commands over and over? Let's make life easier with some aliases. I've categorized them into 'go somewhere', 'do something', or both. With zsh-autosuggestions, you can get what I want done in under 5 keystrokes! The below aliases are designed for working with a phoenix “platform” that uses MinIO in the development environment and a javascript “webapp” front end.

# General
alias g2platform="cd ~/work/platform"
alias g2webapp="cd ~/work/webapp"

# Start applications
alias run_minio="minio server --console-address 127.0.0.1:55649 --address 127.0.0.1:9000 ~/work/minio/data"
alias run_webapp="g2webapp && npm run dev"
alias run_platform="g2platform && iexs"

# Start interactive server session w and w/out minio
alias iexs="iex -S mix phx.server"
alias iexsm="USE_MINIO=true iex -S mix phx.server"

# Reset test enviornment only
alias reset_tests="MIX_ENV=test mix ecto.reset"

alias mixcw="mix compile --warnings-as-errors --return-errors"
alias mixxref="mix xref graph --label compile-connected --fail-above 0"
alias mixsobelow="mix sobelow --compact --skip -v"

# Commands to run before pushing
alias prepush="mix format && mixcw && mix test && mixxref && mixsobelow"

Bonus: What is MinIO?

Curious about MinIO? It's an open-source S3 compatible object store, perfect as a local stand-in for AWS S3. For a deeper dive, here's the original guide that helped me integrate MinIO into my Phoenix project. You can even host your own production MinIO instance on Fly.io.

Check out the diagram below illustrating its role in my local setup, replacing AWS to save everyone from needing AWS credentials:

6. Install Code Editor and Database Client

Unless your an absolute savage and write code in TextEdit, your going to need a code editor and a database client on mac. I use Visual Studio Code and DBeaver, both are free and open source. The mac terminal will do, but I prefer iTerm for its customization options.

# Install Terminal, Code Editor and Database Client
brew install --cask iterm2 \\
             --cask visual-studio-code \\
             --cask dbeaver-community \\
             postgres asdf autoconf wxwidgets 

# Install VS Code Extensions
code --install-extension JakeBecker.elixir-ls --force
code --install-extension phoenixframework.phoenix --force
code --install-extension jamilabreu.vscode-phoenix-snippets --force
code --install-extension eamodio.gitlens --force
code --install-extension dbaeumer.vscode-eslint --force
code --install-extension syler.sass-indented --force

Next we have to add some options in our shell profile to make our editor the default, and a small fix to make the code cli command work.

# Preferred editor for local and remote sessions
if [[ -n $SSH_CONNECTION ]]; then
  export EDITOR='code'
else
  export EDITOR='code'
fi

# Code Launcher fix
code () { VSCODE_CWD="$PWD" open -n -b "com.microsoft.VSCode" --args $* ;}

Must have extensions (installed above)

Honorable Mentions

7. Install Languages

You want to run the code you write, right? If we want erlang to compile correctly we have to add an environment variable with the command:

echo 'export KERL_BUILD_DOCS="yes"' >> ~/.zshrc

asdf plugin-add erlang
asdf plugin-add elixir
asdf plugin-add nodejs

asdf install erlang latest
asdf install elixir latest
asdf install nodejs latest

asdf global erlang latest
asdf global elixir latest
asdf global nodejs latest

8. Install Phoenix Project Generator

One of the best parts of phoenix is its generators and we want to be able to generate a new phoenix project without having to do anything.

mix archive.install hex phx_new

9. Using the script

I hate when I have to copy code section by section from a blog post when I have to try it out, so heres me not doing that to you. I have published this script in its entirety here so in order to run it you can use the commands below

git clone https://github.com/guessthepw/phoenix_dev_setup_script && \
cd phoenix_dev_setup_script && \
cd scripts && \
chmod +x ./mac_setup.sh && \
./mac_setup.sh

Now you can generate a new project, enter the project directory and open the project in your configured code editor with:

mix phx.new hello_world && \
cd hello_world && \
code .

You now have a streamlined and automated setup for your Phoenix development environment. This setup not only saves time but also ensures consistency across your machines. If you have any questions or suggestions, feel free to reach out to me or open an issue on the repo for this post.