Quick Start to Self Hosted Nuvolaris

If you are looking for an hosted service check MastroGPT.

If you instead prefer to self host and install Nuvolaris Community go ahead reading this document.

This is a quick start guide to the installation process, targetting experienced users in a hurry.

It provides a high-level overview of the installation process, omitting advanced of details. The missing pieces are covered in the rest of the documentation.

Of course, if this guide is not enough and things fail, you can always apply the rule: "if everything fails, read the manual".

Prerequisites

Start ensuring the prerequsites are satisfied:

  • Download and install nuv, the Nuvolaris CLI, picking version suitable for your environment. We support 64-bit versions of recent Windows, MacOS and major Linux distributions.

  • Check that nuv is correctly installed: open the terminal and write:

    nuv -info

  • Configure the services you want to enable. By default, Nuvolaris will install only the serverless engine, accessible in http with no services enabled.

If you want to enable all the services, use:

nuv config enable --all

otherwise pick the services you want, among --redis, --mongodb, --minio, --cron, --postgres. Note that --mongodb is actually FerretDB and requires Postgres which is implicitly also enabled. More details here.

Now, choose where to install Nuvolaris.

Your options are:

  • locally in your workstation;

  • in a Linux server in your intranet

  • in a Linux server available on Internet

  • in a Kubernetes cluster in your intranet

  • in cloud, where you can provision a Kubernetes cluster

Local Installation

If you have a decent workstation (with at least 16GB of memory) running a recent 64-bit operating system, you can install Docker Desktop and then install Nuvolaris in it. Once you have:

  1. installed the CLI

  2. configured the services

  3. installed Docker Desktop

Make sure Docker Desktop its running before the next operation. You can install Nuvolaris and its services in Docker with just this command:

nuv setup devcluster

Once it is installed, you can proceed to read the tutorial to learn how to code with it.

NOTE: At least 16GB of memory is ideal, but if you know what you’re doing and can tolerate inefficiency, you can install with less using:

export PREFL_NO_MEM_CHECK=1
export PLEFL_NO_CPU_CHECK=1

Internet Server Configuration

If you have access to a server on the Internet, you will know its IP address.

Many cloud providers also give you a DNS name usually derived by the IP and very hard to remember such as ec2-12-34-56-78.us-west-2.compute.amazonaws.com.

Once you got the IP address and the DNS name, you can give to your server a bettername using a domain name provider. We cannot give here precise instructions as there are many DNS providers and each has different rules to do the setup. Check with your chosen domain name provider.

If you have this name, configure it and enable DNS with:

nuv config apihost <dns-name> --tls=<email-address>

Replace the <dns-name> with the actual DNS name, without using prefixes like http:// or suffixes like :443. Also, replace <email-address> with your actual email address.

then proceed with the server installation.

Server Installation

Once you got access to a Linux server with:

  1. An IP address or DNS name, referred to as <server>

  2. Passwordless access with ssh to a Linux user <user>

  3. At least 8GB of memory and 50GB of disk space available

  4. The user <user> has passwordless sudo rights

  5. The firewall that allows traffic to ports 80, 443 and 6443

  6. Without any Docker or Kubernetes installed

  7. Without any Web server or Web application installed

then you can install Nuvolaris in it.

The server can be physical or virtual. We need Kubernetes in it but the installer takes care of installing also a flavor of Kubernetes, K3S, courtesy of K3Sup.

To install Nuvolaris, first check you have access to the server with:

ssh <user>@<server> sudo hostname

You should see no errors and read the internal hostname of your server.

If you do not receive errors, you can proceed to install Nuvolaris with this command:

nuv setup server <server> <user>

Replace in the commands <server> with the address of your server, and <user> with the actual user to use in your server. The <server> can be the same as <dns-name> you have configured in the previous paragraph, if you did so, or simply the IP address of a server on your intranet

Now wait until the installation completes. Once it is installed, you can proceed to read the tutorial to learn how to code with it.

Cloud Cluster Provisioning

If you have access to a cloud provider, you can set up a Kubernetes cluster in it. The Kubernetes cluster needs to satisfy certain prerequisites to be able to install Nuvolaris with no issues.

We provide the support to easily configure and install a compliant Kubernetes cluster for the following clouds:

At the end of the installation you will have available and accessible a Kubernetes Cluster able to install Nuvolaris, so proceed with a cluster installation.

Amazon AWS

Configure and install an Amazon EKS cluster on Amazon AWS with:

nuv config eks
nuv cloud eks create

then install the cluster.

Azure AKS:

Configure and install an Azure AKS cluster on Microsoft Azure with:

nuv config aks
nuv cloud aks create

then install the cluster.

Google Cloud

Configure and install a Google Cloud GKE with:

nuv config gke
nuv cloud gke create

then install the cluster.

Cluster Install

In short, if you have access to kubernetes cluster, you can install Nuvolaris with:

nuv setup cluster

For a slightly longer discussion, checking prerequisites before installing, read on.

Prerequisites to install

If you have access to a Kubernetes cluster with:

  1. Access to the cluster-admin role

  2. Block storage configured as the default storage class

  3. The nginx-ingress installed

  4. Knowledge of the IP address of your nginx-ingress controller

you can install Nuvolaris in it. You can read more details here.

You can get this access either by provisioning a Kubernetes cluster in cloud or getting access to it from your system administrator.

Whatever the way you get access to your Kubernetes cluster, you will end up with a configuration file which is usually stored in a file named .kube/config in your home directory. This file will give access to the Kubernetes cluster to install Nuvolaris.

Performing the installation

To install, first, verify you have actually access to the Kubernetes cluster, by running this command:

nuv debug kube info

You should get information about your cluster, something like this:

Kubernetes control plane is running at https://api.nuvolaris.osh.n9s.cc:6443

Now you can finally install Nuvolaris with the command:

nuv setup cluster

Wait until the process is complete and if there are no errors, Nuvolaris is installed and ready to go.

Once it is installed, you can proceed to read the tutorial to learn how to code with it.