Installing Cloudillo Yourself

Installing Cloudillo Yourself (Rust Version)

Rust Version

This guide is for the Rust implementation of Cloudillo (v0.1.0-alpha). The Node.js version is deprecated and no longer maintained.

Alpha Software

The Rust version is 70% complete. Core functionality works, but some API endpoints are still in development. See Development Status and Status Page for details.

Before You Begin

  • Review Prerequisites to ensure your system meets requirements
  • Have a domain name ready with DNS control
  • Decide on deployment mode (standalone vs proxy)

Installation Options

You have several options for installing Cloudillo:

  1. Docker (recommended) - Simplest and most versatile
  2. Build from source - For development or custom builds

You also need to decide whether to run in:

  • Standalone mode - Cloudillo handles HTTPS with Let’s Encrypt
  • Proxy mode - Run behind a reverse proxy (nginx, Caddy, etc.)

Running Cloudillo using Docker in Standalone Mode

Warning

Docker images for the Rust version may not be published yet. Check the cloudillo-rs repository for latest status. If not available, use the build from source method below.

Here is the Docker command (adjust image name when available):

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-rs: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-rs:latest  # Adjust when image is published
    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;
	}
}

Building from Source

For the latest features or if Docker images aren’t available yet, build from source:

Prerequisites

# Install Rust (if not already installed)
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
source $HOME/.cargo/env

# Verify installation
rustc --version  # Should be 1.70+
cargo --version

Clone and Build

# Clone the Rust repository
git clone https://github.com/cloudillo/cloudillo-rs.git
cd cloudillo-rs

# Build release version
cargo build --release

# Binary will be at:
./target/release/cloudillo-basic-server

Run the Server

# Set environment variables
export DATA_DIR=/var/vol/cloudillo
export BASE_ID_TAG=agatha.example.com
export BASE_APP_DOMAIN=agatha.example.com
export BASE_PASSWORD=SomeSecret
export ACME_EMAIL=user@example.com
export ACME_TERMS_AGREED=true

# Create data directory
mkdir -p $DATA_DIR

# Run the server
./target/release/cloudillo-basic-server

Next Steps

After installation:

  1. Verify Installation: Access https://your-domain.com
  2. Configure First User: Login with credentials you set
  3. Review Features: Check Status Page for available features
  4. Follow First Steps: First Steps Guide →

Troubleshooting

See Troubleshooting Guide for common issues.

More Information