Welcome to the development environment setup guide.
In here you'll learn how to setup your machine in order to run and develop on this project.
This development environment setup assumes the developer is using macOS.
Windows and Linux instructions are currently not available at the moment, however it is a TODO item.
Xcode Select is Apple's development tools bundle.
One of the needed tools is git, which will be installed with this (among other things).
Install via the following command:
xcode-select --installHomebrew is a 3rd-party package manager for macOS.
It's a command line tool for installing various packages via the command line.
It's similar to apt, yum, apk, emerge, etc. for some distros of Linux.
Refer to the Homebrew site for more information.
Install via the following command:
/usr/bin/ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"NOTE: You may find instruction to install cask. But Homebrew now comes with cask without needing to explicitly install it.
NOTE: There is a Linux (and Windows Subsystem for Linux) version of Homebrew, called Linuxbrew. However, cask packages won't be available.
ASDF VM is a runtime and developer tools version management tool. In short, think of it as something like Node.js Version Manager (NVM) and Ruby Version Manager (RVM), but runtime agnostic. It accomplishes this via plugins. So after you install ASDF VM you'll need to install plugins for the various runtimes.
Why use this?
Because, one of the most frustrating things is getting a consistent development environment across different machines.
No more (mostly) "it works on my machine"-isms.
I can't tell you how many hours teams I've been on has wasted over the years just getting someone's code to just run.
Install via the following command:
brew install asdfThen you'll need to update you're system PATH.
Assuming you're using Z-shell, you'll need to update the ~/.zshrc file.
Update that file by running the following command:
echo 'source $(brew --prefix)/opt/asdf/asdf.sh' >> ${HOME}/.zshrcNOTE: The single quote is important here.
NOTE: You may also need to source the ~/.zshrc file for the system changes to take effect.
Since you'll be installing Node.js via ASDF VM, you'll need to install the Node.js plugin first.
However, there are prerequisites needed by the plugin to install any given version of Node.js.
Install the prerequisites via the following command:
brew install coreutils gpgInstall the plugin via the following command:
asdf plugin-add nodejs
bash ${HOME}/.asdf/plugins/nodejs/bin/import-release-team-keyringSince you'll be installing Python via ASDF VM, you'll need to install the Python plugin first.
Install via the following command:
asdf plugin-add pythonIn the base directory of the project there is a file .tool-versions file.
This is the configuration file used by ASDF VM to both install the missing runtime version, but also use the appropriate runtime restricted the the current directory and all subdirectories in this project (assuming there aren't any additional .tool-versions files in the subdirectories).
Also, ensure that the appropriate ASDF VM plugins and prerequisites have been installed before installing the needed runtimes via ASDF VM.
To install the missing runtimes (if their missing), you'll need to navigate to the base directory of this project and run the following command:
asdf installEven though you now have the runtimes installed, you'll need to perform some final steps to properly setup Node.js.
Install node-gyp globally. In the event that some Node.js dependencies require native extensions to be compiled, you'll need node-gyp (and Python2).
Install node-gyp globally with the following command:
npm install --global node-gypNOTE: Notice that sudo wasn't used for the global installation. That is because ASDF VM doesn't install Node.js in system directories which may require permissions.
NOTE: Also, configurations and global installs that are applied to runtime typically don't carry over to another installed version. This is because ASDF VM treats different installed versions as septate software independent of each other. The only exception to this would be runtimes that store configurations or plugins or etc. in directories that ASDF VM doesn't control. For example, local NPM dependencies stored in project node_module folders.
No post installation steps.
NOTE: Also, configurations and global installs that are applied to runtime typically don't carry over to another installed version. This is because ASDF VM treats different installed versions as septate software independent of each other. The only exception to this would be runtimes that store configurations or plugins or etc. in directories that ASDF VM doesn't control. For example, local virtual environments created by Python's virtualenv or venv modules.
This project uses the NestJS framework. Therefore, it depends on the NestJS CLI, which needs to be installed globally.
Ensure that you've installed Node.js via ASDF VM and you're currently using it, such as having you're working directory be in this project's directory (and/or subdirectories).
To install it, do so via the following command:
npm install --global @nestjs/cliBecause the Docker engine cannot natively run on macOS, you'll need to install Virtualbox and run Docker through a Linux virtual machine. Sounds complicated? That's because it is, but only in terms of how it works, in reality using it is as smooth as if you have it working natively with the system.
Install Virtualbox via the following command:
brew cask install virtualbox virtualbox-extension-packNOTE: You'll be prompted to enter you're password.
Docker Machine is a tool used to setup the Linux virtual machine so that Docker can be used.
You'll also need Docker Machine NFS. Unfortunately, mounting volumes in with Docker tends to have file permission issues, such as non-root users in the Docker container sometimes not being able to write to folders mounted to the Docker container (e.g. docker ... --volume ...). Fortunately, Docker Machine NFS fixes this.
Install Docker and Docker Machine via the following command:
brew install docker docker-machine docker-machine-nfsNOTE: Docker Compose comes with the Homebrew docker package.
Create the Docker Machine called vbox-blogexample2 (actually you can name it whatever you want, but we're calling it this for our purposes) via the following command:
docker-machine create --driver virtualbox vbox-blogexample2Then you'll need to update you're system's environment variables.
Assuming you're using Z-shell, you'll need to update the ~/.zshrc file.
Update that file by running the following command:
cat <<'SHELL' >> ${HOME}/.zshrc
if [[ $(docker-machine status vbox-blogexample2) == 'Running' ]]; then
eval "$(docker-machine env vbox-blogexample2)"
fi
SHELLNOTE: The single quote is important here.
NOTE: You may also need to source the ~/.zshrc file for the system changes to take effect.
NOTE: With system restarts you may get an error like this: docker: Cannot connect to the Docker daemon at unix:///var/run/docker.sock. Is the docker daemon running?.. To fix this just start the Docker machine with this command: docker-machine start vbox-blogexample2 and source the ~/.zshrc file again.
Activate NFS on the project folder so the MongoDB can mount project folders properly with the correct permissions.
For more information on Docker Machine NFS refer to the documentation found on it's README file.
We're altering this Virtualbox machine to be used to mount volumes in the project directory using Docker Machine NFS. This will avoid permissions issues with between the Docker container and host folders, however this will mean that mounting folders outside this project won't function properly. Therefore, it's necessary to create a new Docker machine exclusive to this project. Don't worry about eating up too much storage on your machine, the Virtualbox Docker machines are relatively cheap on resources, taking up ~1GB of memory, 1 CPU core, and ~70MB per machine.
docker-machine-nfs vbox-blogexample2 --shared-folder=$(pwd) --nfs-config="-alldirs -maproot=0"NOTE: You wil be asked for you password. This is because Docker Machine NFS needs root permissions to edit /etc/exports.
We'll need to create a Docker network so that the containers can comminate with each other via their hostname, leveraging Docker's builtin DNS.
Create Docker network blog-example-2 via the following command:
docker network create blog-example-2Pull the official Node.js Docker image, node:10.19.0-buster-slim, via the following command:
docker pull node:10.19.0-buster-slimNOTE: Documentation on how to use this container can be found here.
Pull the official MongoDB Docker image, mongo:4.2.3-bionic, via the following command:
docker pull mongo:4.2.3-bionicNOTE: Documentation on how to use this container can be found here. Look for the "How to use this image" section.
Pull the official Elasticsearch Docker image, elasticsearch:7.6.0, via the following command:
docker pull elasticsearch:7.6.0NOTE: This image is based on CentOS 7.
NOTE: Documentation on how to use this container can be found here.
NOTE: Documentation on how to use Elasticsearch can be found here.
While not strictly required for this project operate properly, they are nice to haves that'll make development much smother.
It's always good to have an IDE. Visual Studio Code is an excellent an popular choice.
brew cask install visual-studio-codeAnother nice-to-have feature would be to the ability to launch the IDE from the command line.
You can do this by updating the ~/.zshrc file with the following function definition.
This will allow launch the IDE with the following terminal command: code.
Update that file by running the following command:
cat <<'SHELL' >> ${HOME}/.zshrc
function code {
/Applications/Visual\ Studio\ Code.app/Contents/MacOS/Electron "$@"
}
SHELLNOTE: You may also need to source the ~/.zshrc file for the system changes to take effect.
Postman is a REST API client.
brew cask install postmanNOTE: You may be asked to enter your password to install.
MongoDB Compass is a GUI for interacting with MongoDB and visualizing it's contents.
If you're familiar with tools like: phpPgAdmin (for Postgres), phpMyAdmin (for MySQL/MariaDB), phpLiteAdmin (for SQLite), etc.; it's the same idea.
brew cask install mongodb-compassNOTE: You may be asked to enter your password to install.