Skip to main content

Install MonkOS Locally

Here's how you install, test, and upgrade Monk.

Prerequisites

MonkOS requires Podman to be present and running on your system.

APT and Homebrew packages will install Podman for you.

If you're not installing from the above sources, please check out how to install Podman prior to installing MonkOS.

Prerequisites

MonkOS on macOS requires Command Line Tools version 14.3. If you are using an earlier version of the Command Line Tools, you will be prompted to upgrade as part of set up. Note that the version of Command Line Tools is separate from the version of Xcode. If you are unsure what version of Command Line Tools you are running, you can check with:

softwareupdate --history | grep "Command Line Tools" | tail -n 1

Installing Monk​

Installing with Homebrew

We provide a Homebrew repository containing official releases of Monk. You can obtain the latest stable version of MonkOS from this repository by running the following command:

brew install monk-io/monk/monk

Now enable Monk machine to have monkd running in the background:

monk machine init

Monk machine is a lightweight Linux VM that runs monkd on your mac. After this step you don't have to start monkd by hand.

tip

All done! Please proceed to the next section to try monk out.

Testing Your Setup​

In a new terminal, run:

monk login

After logging in, you should be able to list the available Kits like so:

monk list

The command should return available Kits if the installation was successful, but sometimes it may take up to 30 seconds to sync the Kits. If you don't see a list at first, just retry in a few seconds.

Type      Template              Repository    Version   Tags
runnable  chatwoot/chatwoot     local         latest    self hosted, messaging, communication
runnable  chatwoot/mailhog      monk          latest    smtp, email
runnable  chatwoot/sidekiq      local         latest    self hosted, messaging, communication
group     chatwoot/stack        monk          latest    self hosted, messaging, communication
....

If you see similar output it means that the installation was successful and you may now start using MonkOS on your system 🎉

Continue to the Guides section to see how you can use Monk.

If for some reason the command didn't work, please check if you have followed all instructions.

Upgrading Monk​

Upgrading your local MonkOS to the newest version is simple.

brew upgrade monk
monk machine rm
monk machine init

If you have a cluster running:

  1. Make sure you are connected to the cluster (monk cluster info),
  2. Make sure your local MonkOS is the latest version,
  3. Run monk system upgrade to upgrade all the nodes to the newest version.

Installation Impact​

MonkOS aims to be a good steward of your filesystem and not scatter files throughout the disk. The MonkOS distribution is simple and consists of two binaries, monkd and monk.

Our apt ot brew packages bring podman as a dependency and install it on your system if it is not present.

When installing with apt or brew those are placed or symlinked in /usr/local/bin. apt on Linux configures your systemd to start monkd as a service immediately after install and on system startup. Additionally, a monkd user group is created and assigned appropriately.

All data files needed for MonkOS' operation are created in /var/lib/monkd (Linux) and ~/.monk (both Linux and macOS) upon first monkd startup.

The monk command will install bash and zsh autocompletion in your dotfiles on first use. Changes to the dotfiles are reversed upon package removal.

Rate this page