TonicsCloud Documentation

TonicsCloud 🌧️ is a Domain specific project under the TonicsCMS.

It is an open source system container server management tool that leverages the flexibility of system containers such as Incus and VPS API for provisioning the server and managing DNS.

Why I Built TonicsCloud

…so I can host multiple application/projects on a server in a truly isolated way.

There are several ways this can be done but they are mostly insecure in the sense that, a vulnerable app or project in the server might affect other application since they are not entirely isolated from each other anyway.

Another way is using an application container such as docker, while this is a good idea, application container doesn’t fit my use case.

I want that touch of a traditional server and that is where system container comes in. It gives you the feel of a traditional server with the added benefits of containerization and the ability to run multiple processes at the same time.

In essence, what I am looking for is container isolation in a sever with no too many limitation as to what I can do with my container.

For small agency, you can pack multiple website on one server in a truly isolated way and for personal use, you can host projects on a server without the need of provisioning new servers for each project.

Target Audience

For hosting personal projects
Web Agencies that want to manage hosting for their clients, there is an option to charge clients directly
Developers
For pet projects
and anyone that would love to host multiple apps on one server

How Does Hosting Works in TonicsCloud

Everything you do lives in your server, TonicsCloud support multiple VPS Providers (currently Linode & UpCloud), so, all you have to do is plug in the API credentials from your preferred Provider and you are good to go.

TonicsCloud uses a system container to isolate one container from one another.

Once your server is provisioned from the TonicsCloud interface, you have the luxury to host multiple things (containers) in your server without any interference whatsoever from other container on the server.

Here are an example of things you can do on just one server:

Website Hosting
Mail Server
Database Server
Application Hosting
Development Environment
Proxy Server
and whatever you can do on a typical Linux distro

There is no limit to what you can have in your containers.

Installation

Note: While TonicsCloud is open-source, it is not free, to receive timely updates + security patches, you need to buy the plugin, though you can still use it for free, you just won't get any updates.

If you sign up and deploy a cloud instance using the sign up link below, I would give you a free yearly update, contact me: olayemi@tonics.app

The faster way of installing TonicsCloud is by supporting me and trying it here: https://tonics.app/customer/signup, here is a guide: Tonics » Installing TonicsCloud
If you know your way around the command line, you can also install TonicsCloud manually by following the instructions here: Tonics » Getting Started (Overview and Installation). (Not recommended, but okay for testing)

Building this project cost money and effort, I have been working on the TonicsCMS itself since 2021, and I started TonicsCloud last year, if you use the link above to signup, you are in essence supporting the project, and would be use to fix bugs and new features, thanks 🙏🏾

Using TonicsCloud

There are two sides to TonicsCloud, the Admin Panel and the Customer Panel, let's unpack the both...

Skip the Admin Panel section if you signup through tonics.app and you just want to host applications. The Admin panel is for developers using TonicsCloud itself.

Admin Panel

The admin panel is where you oversee the core operation of TonicsCloud, where you configure the VPS API Key, the Deployment options, amount to charge your client per price plan and if you are not hosting app for client, you can also turn off the billing option and so many more.

If you haven’t logged in, do so through: yourwebsite.com/admin/login where yourwebsite.com is the name of your website.

To configure the TonicsCloud settings, go-to: Tools → Apps

If TonicsCloud is not installed yet, push the install button, then click on TonicsCloud settings:

click on TonicsCloud settings

then you should see the settings page, e.g., something like below:

TonicsCloud Settings Page

Note: If you see an empty Settings Page, please uninstall TonicsCloud and install it again.

As you can see, the TonicsCloud settings are separated by Tabs, there are no explanation to do here as there are self-explanatory, I have highlighted the section in red with a number for the below number list:

This is the main tab
This is the individual Cloud Provider tab and upon clicking each provider, you get...
The Cloud Provider Settings
To Save Changes

The rest of the Admin Panel section would be F.A.Q about doing common settings in TonicsCloud relating to the Admin side.

What Are The Necessary First Step I Need To Take?

Configure your mail settings!

By configuring your mail settings, you ensure that mails get delivered when your customer sign up, notices, etc.

To Configure the mail settings, go-to: Tools → App

The click on the Core Settings, that would take you to the Core Settings Page and then you can click the Mail Tab, this is where you edit the mail settings.

Once you are done, hit the Save button and you are good to go.

To ensure things are working as expected, sign-up as a test user and check if you can receive mail.

How Do I Ensure Fast Instance Deployment?

Deploying instance or server is slow, this is because of the configuration TonicsCloud needs to do to make it TonicsCloud ready, it can take anywhere between 3 minutes to 7 minutes depending on the Cloud Server integration you are using.

To make instance deployment faster (1 minute or less), I have a custom solution for paying customers, it is on auto pilot, it builds a golden image for you on schedule, and attaches that to the private image of the supported cloud servers.

This way, whenever a customer is deploying an instance, it uses the golden image instead of doing the configuration from scratch.

Feel free to send me a message: olayemi@tonics.app if you want to discuss further about the solution.

How Do I Enable/Disable Billing?

By default, charging customers is disabled, please turn that ON by setting the Enable Billing to True. The option is located in the Others Tab of the TonicsCloud Settings Page.

How Do I Choose a VPS Provider/DNS Provider?

You can choose the VPS Provider you want for server provisioning in the Cloud Server Tab of the TonicsCloud Settings Page.

You can also choose the DNS provider that would manage the DNS in the DNS Tab, DNS management is totally optional, depending on your use case, so, you can keep your DNS records or management at wherever place you are currently managing it.

How Do I Customize The Provider Region/Prices?

In the Core Tab, you would see Tabs of the supported VPS Provider, on each Provider, you have the option to edit the provider or region.

Note 1: The prices should be compatible with whatever your server provider is using, you do not have to use every of your provider prices, however, ensure the key maps with the one your provider is using. I have provided the common ones but you can add more depending on your use case.

Note 2: Once a price key is saved, it can not be deleted (price, description, etc can be updated, you can't just delete the price key), however you can add new ones, this does not apply to the regions, it can be deleted and updated at will.

The prices is in the following JSON structure:

{
  "g6-nanode-1": {
    "service_type": "Server",
    "description": "Shared 1GB RAM - 1CPU Core - 25GB SSD",
    "price": {
      "monthly": 12
    },
    "memory": 1024,
    "disk": 25600,
    // more properties if there is one
  },
  "new-entry-key": {
    "service_type": "Server",
    "description": "Your new description here",
    "price": {
      "monthly": 50
    },
    "memory": 8192,
    "disk": 163840,
    // more properties if there is one
  }
...
}

In the above specific JSON object:

Each key represents a unique identifier for a server configuration (e.g., "g6-nanode-1").
Each value is an object containing details about the server configuration, including its service type, description, price, memory, and disk specifications.
Depending on the VPS Provider, you might want to ensure some of the value of the properties match, e.g, ensure the memory, disk or core matches with what the provider is using, you can also check their API.
The prices can be set to whatever you want to charge your customer, for example, if the Provider is charging $7 for the server per month, you can set it to $10 or $15 depending on what you want to charge your customer per month.

The regions are in the following JSON structure:

[
  {"label":"Dallas, TX","id":"us-central"},
  {"label":"Mumbai, IN","id":"ap-west"},
  ...
]

"label": representing the name of the location (e.g., "Dallas, TX").
"id": representing the identifier or code for the location (e.g., "us-central").

Note: The region should be compatible with whatever your server provider is using.

Is SSH Required?

NO!

TonicsCloud does not use SSH, however, there is a development mode which gives you access into the host server, this way, you can do some testing.

Production mode nukes SSH as it isn’t needed for production and instead leverages the system container API.

However, depending on the app you are using on your container, you can enable it on a per container basis if there is an App for that.

How Does TonicsCloud Ensure Secure Connection?

TonicsCloud leverages the system container (Incus) API to talk to the provisioned server and this is done securely with the client certificates.

The client and the server generate a key pair the first time they’re launched (This is done while the server is provisioning).

The server uses that key pair for all HTTPS connections to the Incus socket.

The client uses its certificate as a client certificate for any client-server communication.

TonicsCloud is the client in this case. It uses its client certificates to securely communicate with the Incus server via the system container API.

This ensures that all communications between TonicsCloud and the Incus server (provisioned server) are secure and authenticated.

What Is an Image in TonicsCloud?

Image is the template that would be used to create the container, for example, WordPress image contains all the necessary programs for spinning WordPress instance, the good thing about this image base approach is that you can spin new container in a matter of seconds.

The core images are published here: TonicsCloud Hub, they contain public images you can use in TonicsCloud and by default they are included in TonicsCloud.

How Do I Add Additional Images?

To Add a new Image, Go-To: Tools -> Apps -> Cloud → Images → Add New

You can have several version of an image, and multiple image link mirrors, TonicsCloud would pick at random.

The image would be included in the container creation page whenever user want to deploy a container.

The image apps is vital, they are separated by comma and as long as TonicsCloud supports them, it would show as an option for user when a container is deployed, off-course, it can be extended to support more apps.

Here are the current list of supported Apps:

PHP
MariaDB
Nginx
ACME
ENV
Script
Unzip
Haraka
More Coming…

Think of the App as an actual program, just that in the case of TonicsCloud, it is interfacing with a particular program in the container.

Customer Panel

The customer panel is where you deploy instances and containers.

If you haven’t logged in, do so through: yourwebsite.com/customer/login where yourwebsite.com is the name of your website.

or if you have signed up with tonics.app, you can access your dashboard at tonics.app/customer/login

To make this section interesting and easy to follow, I would turn the rest of the section into a F.A.Q. Let’s go…

How Do I Deploy and Instance or Server?

To Add a new Instance, Go-To: Cloud → Instances → Add New

You would see the instance form, it is self-explanatory, choose the instance name, the region you want the instance to be deployed to and the plan you want.

Hit Deploy Instance to deploy it, then wait for a while for the instance to be configured, might take between 2 minutes to 5 minutes, chill out 😉

Deploying Instance Seems To Be Stuck, How Do I Track The Progress?

The current version of TonicsCloud does not support live update for the instance progress, I have added a Reload button in the Datable, hit the Reload button to track the changes.

Why is Deploying Instance Taking So Much Time?

This is because TonicsCloud needs to configure the server for it to be TonicsCloud Ready, meaning, installing the system container, configuring the server to be secure and preparing some components TonicsCloud would use.

Depending on the cloud provider integration the admin is using, the deployment can take between 1 minutes to 7 minutes, if it takes longer than that, please, terminate the instance and redeploy.

How Do I Terminate a Stuck Instance?

To Terminate an Instance, click on the Cloud menu, that would take you to the list of all instances, terminate an instance by clicking on the Sig option and choosing Terminate.

Deploying Instance Is Stuck At Preparing Instance, What Should I Do?

Sometimes, the cloud provider the admin uses might be buggy, for example, Linode VPS Provider occasionally wouldn’t trigger the stackscript attached to the instance on time and as such, TonicsCloud get stuck at Preparing Instance.

UpCloud VPS Provider does not have this problem.

Wait for 8 minutes max, and if you are still stuck, please terminate the instance by clicking on the Sig option and choosing Terminate.

The Instance is Deployed, How Do I Add a Container?

Click on Add Container in the Instance DataTable or go-to:

Cloud → Containers → New Container