Installing IHP
1. Dependency: Nix Package Manager
The framework uses the nix package manager to manage the whole set of dependencies of your application. Nix is the equivalent of npm, but for Haskell and much more.
For example, PostgreSQL and the Haskell compiler are both dependencies of your app, as well as all the Haskell or JavaScript packages you want to use. We use nix to make sure that these dependencies are available to the app - in development, as well as in production.
That’s why we first need to make sure that you have nix installed.
Mac
Run this command in your terminal to install nix on your machine:
curl --proto '=https' --tlsv1.2 -sSf -L https://install.determinate.systems/nix | sh -s -- install
We use the Determinate Nix Installer instead of the normal Nix installer here as it works better on macOS, e.g. the normal Nix installer always breaks across macOS updates.
After this restart your terminal.
Linux
Before installing nix and IHP, you need curl and git if you don’t have them already. If you are unsure, run this:
sudo apt update
sudo apt upgrade
sudo apt install git curl make -y
For NixOS Users: If you’re on NixOS, of course you don’t need to install nix anymore :-) Just skip this step.
Install nix by running the following command in your shell and follow the instructions on the screen:
curl -L https://nixos.org/nix/install | sh
Due to Linux not loading the .profile file, nix will not be loaded. To fix that, we need to add this line to the rc file of your shell (usually .bashrc). Open it, and add this line
. ~/.nix-profile/etc/profile.d/nix.sh
There are also other ways to install nix, take a look at the documentation.
Windows
Running nix on Windows requires the Windows Subsystem for Linux, which first needs manual activation via Powershell with Administrator Privileges:
dism.exe /online /enable-feature /featurename:Microsoft-Windows-Subsystem-Linux /all /norestart
Enabling this Feature needs a restart (even though it won’t prompt, and the command-line says /norestart).
To download a Linux Distribution, open the Microsoft Store and search for Ubuntu or Debian. We recommend Ubuntu since it works best with nix on Windows.
Note: You do not need a Microsoft account to download. You can simply cancel or close the login forms and the download will continue.
If this is your first time installing WSL and you are encountering problems, rest assured most issues are well-known and solutions can be found online by searching the web for the error messages.
With the Distro downloaded, run it and update it using your package manager. In Ubuntu you would use:
sudo apt update
sudo apt upgrade
sudo apt install git curl make xdg-utils -y
WSL will add your Windows System Paths in your Linux Subsystem. These tend to generate errors due to spaces and brackets in folder names. Also, due to Linux not loading the .profile, we need to add the nix.sh manually. To fix these two issues, just add these lines to the end of your .bashrc
PATH=$(/usr/bin/printenv PATH | /usr/bin/perl -ne 'print join(":", grep { !/\/mnt\/[a-z]/ } split(/:/));')
. ~/.nix-profile/etc/profile.d/nix.sh
Now, create a folder for nix:
sudo mkdir -p /etc/nix
To make nix usable on Windows, we need to create and add the following lines to the file /etc/nix/nix.conf (requires use of sudo again):
sandbox = false
use-sqlite-wal = false
After saving the file, you can now install nix:
curl -L https://nixos.org/nix/install | sh
When the installation finishes successfully, you will be prompted to either reload your environment with the given command, or restart your shell.
If in doubt, just close and reopen Ubuntu/Your Distro.
NOTES FOR WINDOWS USERS:
Windows Firewall
When using Windows, you will be asked if tasks like ghc-iserv or rundevserver should be allowed by the firewall. This is needed to access the devserver interface and the web application itself.
Installing nix for IHP was done using this guide.
Note that nix can gradually grow to use several GB of disk space, especially after upgrading IHP. You can always run nix-collect-garbage in a nix-shell which will delete older/unused files.
Optional: Enabling Flakes
Flakes is an experimental part of Nix, so the installation steps above would not have enabled this useful feature.
IHP uses Flakes, but only internally and without affecting the rest of your Nix environment. Enabling it for your whole Nix environment is optional, but we believe it’s a great feature that’s well worth learning and using in your projects!
To enable Flakes, add the following line to ~/.config/nix/nix.conf (or /etc/nix/nix.conf to enable flakes for every user on your machine):
experimental-features = nix-command flakes
If you are unsure, we recommend enabling Flakes. For a beginner’s guide, see this NixOS & Flakes Book.
2. Installing IHP
You can now install IHP by running:
nix-env --install ihp-new
If you use Home Manager or NixOS, you can also add ihp-new to the list of packages. If you use nix flakes, you likely want to run nix profile install nixpkgs#ihp-new instead.
GitHub Codespaces / VSCode Devcontainers
To get started with IHP on GitHub Codespaces, simply use the Codespaces IHP Template to create a new GitHub repo. On the first start up, a new IHP boilerplate will be generated which you can commit.
To try it out before making your own repo, you can simply start a Codespace from the template itself.
If you have Docker installed locally, then you can use this configuration to work with VSCode Devcontainers as well.
GitPod
If you use GitPod for Development in the Cloud, you can use IHP GitPod Template.
On first start up, GitPod will automatically generate a new IHP project for you. You just need to call git add . and then commit the boilerplate after first start.
If you want to try it out before making your own repo, use this button below:
3. Setting up your editor
Also check this out if your editor is already set up. You might miss a plugin that’s recommended for IHP to work well.
- VS Code Don’t have the direnv extension installed? Read this link
- Sublime Text
- Emacs
- Vim / NeoVim
It’s time to start your first “hello world” project now :)
