Installing Cloudillo Yourself

You have several options for installing Cloudillo. The simplest and most versatile is using Docker Another thing you should decide is whether you want to run Cloudillo in standalone mode or in proxy mode. The latter is useful if you want to run Cloudillo behind a reverse proxy.

Running Cloudillo using Docker in Standalone Mode

Here is a simple one-liner:

docker run -d --name cloudillo \
  -v /var/vol/cloudillo:/data \
  -p 443:443 -p 80:80 \
  -e LOCAL_IPS=1.2.3.4 \
  -e BASE_ID_TAG=agatha.example.com \
  -e BASE_APP_DOMAIN=agatha.example.com \
  -e BASE_PASSWORD=SomeSecret \
  -e ACME_EMAIL=user@example.com \
  -e ACME_TERMS_AGREED=true \
  cloudillo/cloudillo:latest

You basically need a local directory on your server and mount it to /data inside the container and publish port 443 (HTTPS) and 80 (HTTP). You can read about the configuration environment variables below.

Cloudillo in standalone mode uses TLS certificates managed by Let’s Encrypt. If you want to use different certificates then you have to use Proxy Mode.

Warning

For Let’s Encrypt certificate issuance to work you have to ensure that $BASE_APP_DOMAIN and cl-o.$BASE_ID_TAG both have DNS A records pointing to one of $LOCAL_IPS before first starting the container.

Here is a docker-compose for the same:

version: "3"
services:
  cloudillo:
    image: cloudillo/cloudillo:latest
    container_name: cloudillo
    volumes:
      - /var/vol/cloudillo:/data
    ports:
      - 443:443
      - 80:80
    environment:
      - LOCAL_IPS: 1.2.3.4
      - BASE_ID_TAG: agatha.example.com
      - BASE_APP_DOMAIN: agatha.example.com
      - BASE_PASSWORD: SomeSecret
      - ACME_EMAIL: user@example.com
      - ACME_TERMS_AGREED: true

Warning

You should change the default password as soon as possible!

Configuration Environment Variables

Variable	Value	Default
MODE	“standalone” or “proxy”	“standalone”
LOCAL_IPS	Comma separated list of IP addresses this node serves	*
BASE_ID_TAG	ID tag for the admin user to create	*
BASE_APP_DOMAIN	App domain for the admin user to create	*
BASE_PASSWORD	Password for the admin user to create	*
ACME_EMAIL	Email address for ACME registration	-
ACME_TERMS_AGREED	Whether to agree to ACME terms	-
DATA_DIR	Path to the data directory	/data
PRIVATE_DATA_DIR	Path to the private data directory	$DATA/priv
PUBLIC_DATA_DIR	Path to the public data directory	$DATA/pub

In case you are not familiar with the Cloudillo Identity System we provide some information about the notions used above:

The ID tag is the unique identifier of a Cloudillo profile. It can be any domain name associated with a user.

The App Domain is the domain address used by the user to access their Cloudillo shell. Currently the App Domain is also unique for every user, but it might change in the future. It is preferably the same as the ID tag of the user, but it can be different when the domain is used by an other site.

For a domain to work as a Cloudillo Identity it must serve a Cloudillo API endpoint accessable at the cl-o subdomain. In the above example you have to create the following DNS records:

Name	Type	Value	Purpose
agatha.example.com	A	1.2.3.4	App domain (APP_DOMAIN)
cl-o.agatha.example.com	A	1.2.3.4	API domain (cl-o.ID_TAG)

Running Cloudillo using Docker in Proxy Mode

An other one-liner:

docker run -d --name cloudillo \
  -v /var/vol/cloudillo:/data \
  -p 1443:1443 \
  -e MODE=proxy \
  -e LOCAL_IPS=1.2.3.4 \
  -e BASE_ID_TAG=agatha.example.com \
  -e BASE_APP_DOMAIN=agatha.example.com \
  -e BASE_PASSWORD=SomeSecret

In proxy mode you have to provide your own solution for TLS certificates. In proxy mode Cloudillo serves its API port on 1443 but using HTTP and it doesn’t serve the HTTP port by default. You should provide your own redirections. However, you can turn it on with the LISTEN_HTTP=1080 environment variable.

We provide an example nginx configuration:

server {
	listen   80;
	server_name  agatha.example.com cl-o.agatha.example.com;

	location /.well-known/ {
		root    /var/www/certbot;
		autoindex off;
	}
	location / {
		return 301 https://$host$request_uri;
	}
}

server {
	listen 443 ssl;
	server_name agatha.example.com cl-o.agatha.example.com;
	ssl_certificate /etc/letsencrypt/live/agatha.example.com/fullchain.pem;
	ssl_certificate_key /etc/letsencrypt/live/agatha.example.com/privkey.pem;

	location /.well-known/cloudillo/id-tag {
		add_header 'Access-Control-Allow-Origin' '*';
		return 200 '{"idTag":"agatha.example.com"}\n';
	}
	location /api {
		rewrite /api/(.*) /api/$1 break;
		proxy_pass http://localhost:1443/;
		proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
		proxy_set_header X-Forwarded-Proto https;
		proxy_set_header X-Forwarded-Host $host;
		client_max_body_size 100M;
	}
	location /ws {
		proxy_pass http://localhost:1443;
		proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
		proxy_set_header X-Forwarded-Proto https;
		proxy_set_header X-Forwarded-Host $host;
		proxy_set_header Upgrade $http_upgrade;
		proxy_set_header Connection "Upgrade";
	}
	location / {
		# You can serve the cloudillo shell locally, or proxy it.
		root /home/agatha/cloudillo/shell;
		try_files $uri /index.html;
		autoindex off;
		expires 0;
	}
}

Installing Cloudillo from Source

You can visit Cloudillo’s GitHub page for instructions:

https://github.com/cloudillo/cloudillo