GuidesRecipesAPI ReferenceChangelogDiscussions
Log In

"One Box" Installation


Estimated Completion Time: ~60 minutes

Modzy is designed to run in a highly-available, horizontally-scalable manner, but from time to time, it is desirable to install Modzy on as little hardware as possible. This guide outlines an installation method that will allow Modzy to be installed and run on a single box. All Modzy components as well as models will only run on this single box.

Note: This installation method is not highly available and cannot be scaled beyond the single box. If higher scalability is desired, a brand new and highly available installation of Modzy will be required. See our recommended installation requirements page for more details.

System Requirements

CPU16 cores
Storage500 GB
Operating SystemLinux (tested on Ubuntu 20.04 LTS)

Install k3s

For our Kubernetes distribution, we'll be using k3s. The following command uses a version based on Kubernetes 1.21 but any version less than 1.25 should also work. Modzy does not yet support Kubernetes 1.25+.


Using a (more) secure token

Any value for the --token parameter can be supplied in the following command. Since this is a single-box install, we won't be joining any additional nodes to this cluster so the value is irrelevant.

curl -sfL | INSTALL_K3S_VERSION=v1.21.12+k3s1 sh -s - server --disable traefik --cluster-init --node-label "" --token modzy

If you plan on using a self-signed certificate for this installation, then you'll need to configure k3s to accept self-signed certificates for Modzy's registry URL. Replace <FQDN> with the fully-qualified domain name that you will be hosting Modzy under.

sudo vim /etc/rancher/k3s/registries.yaml
      insecure_skip_verify: true

Now restart the k3s service to have the changes take effect.

sudo systemctl restart k3s.service


Using kubectl

The next steps can be performed directly on the box or on your own machine. If you would likekubectl access from your own machine, copy the contents of /etc/rancher/k3s/k3s.yaml to your machine and update the URL to point to the IP address of the box instead of

Install Modzy


Single Box Installation Notice

This guide assumes that in addition to running on a single box, you also don't want any external dependencies beyond setting up DNS which is always required.

Modzy is installed, configured, and upgraded using KOTS. To begin, download the kubectl plugin:

curl | bash

Next, let's start the Modzy installation process!

kubectl kots install modzy -n modzy

This procedure is the same as the standard installation of Modzy. Reference this guide for screenshots and more detailed information.

Otherwise, follow the view the below instructions, which provide all the information you need to set up the Configuration in the Admin Console:

  1. Use the password you defined when spinning up the admin console for the first time to log in
  2. Upload your Modzy license file
  3. For the installation profile, choose "Minimal". This will tell Modzy to only deploy one pod for each service.
  4. In the Security section, keep the "Verify TLS" box checked if you are using a valid certificate. If you are using a self-signed certificate, this box should be unchecked. Next, choose the "Embedded Identity Provider" option.
  5. In the Ingress Settings section, add your FQDN in the Domain field.
  6. For TLS, choose "Self-Signed".
  7. Choose "Use the embedded database"
  8. For the object storage configuration, choose "Embedded".
  9. For SMTP settings, you can just enter localhost for the Host and no-reply@localhost for the From Address.

Finally, save config and deploy the Modzy installation.

First User Login

Pending a successful installation, navigate to the Modzy site via your FQDN. This will take you to a Keycloak login page (assuming you used the "Embedded Identify Provider" option). Modzy automatically creates the first user for you with the following credentials:

  • Username: platform-admin@<FQDN>
  • Password: modzy

Use these credentials to login to the Modzy application.