Getting Started

Welcome to the Cosmos documentation. There are two ways to run Cosmos

  • (BETA) as a standalone service on your system. This will be the recommended way to run Cosmos moving forward, as it will allow you to use all of its features. It is currently still new, so if you find an issue with the installtion, please report it on Discord or Github! Go to the standalone service section to learn how to install Cosmos this way.

  • as a Docker container. This is the easiest way to run Cosmos, but it will limit some of its features. Especially for the storage management. Go to the Docker container section to learn how to install Cosmos this way.

The two version are interopaerables, you can switch from one to the other without any issue, just make sure they have the same env variables and config folder.

Install Cosmos as a standalone service

Automatic installation

You can install Cosmos with the following command:

# IF YOU NEED TO CHANGE THE PORTS, DO IT BEFORE RUNNING THE COMMAND
# You can overwrite any other env var by adding them here
export COSMOS_HTTP_PORT=80
export COSMOS_HTTPS_PORT=443

# You can run a dry run to see what will be installed
curl -fsSL https://cosmos-cloud.io/get.sh | sudo -E bash -s -- --dry-run

# If you are happy with the result, you can run the command
curl -fsSL https://cosmos-cloud.io/get.sh | sudo -E bash -s

This command will install/update dependencies such as Snapraid, Avahi, Docker, Docker-Compose, ... and finally install Cosmos as a service. It will also check your firewall setup and start the service. You can check the script here. Before running it.

If Cosmos fails to start, you can either check the logs with sudo journalctl -u CosmosCloud or check the logs in the config folder at /var/lib/cosmos/cosmos.log.

Finally, you can see the logs directly by starting Cosmos manually with 

sudo /opt/cosmos/cosmos

Manual installation

If you prefer to install Cosmos manually, you can follow the following steps:

  1. Install Docker and Docker-Compose. You can find the installation instructions on the official Docker website.

  2. Install dependencies

# for debian/ubuntu
sudo apt-get update
sudo apt-get install -y ca-certificates openssl fdisk mergerfs snapraid

# for centos
sudo yum install -y ca-certificates openssl fdisk mergerfs snapraid

# for fedora
sudo dnf install -y ca-certificates openssl fdisk mergerfs snapraid

# for arch
sudo pacman -Sy ca-certificates openssl fdisk mergerfs snapraid

  1. Download the latest release of Cosmos from the GitHub releases page and extract it to a folder of your choice.

  2. Run the following command to start Cosmos:

cd /path/to/cosmos
sudo ./cosmos service install
sudo systemctl start CosmosCloud

This will create a systemd service for Cosmos and start it.

Management

The resulting Cosmos daemon is a systemd service. You can manage it with the following commands:

sudo systemctl start CosmosCloud
sudo systemctl stop CosmosCloud
sudo systemctl restart CosmosCloud
sudo systemctl status CosmosCloud

# If you want to see the system logs
sudo journalctl -u CosmosCloud

You can also find the logs directly in the config page OR in the config folder:

# If you want to see the Cosmos logs
cat /var/lib/cosmos/cosmos.log

# If you want to see the plain logs (without the terminal formatting)
cat /var/lib/cosmos/cosmos.plain.log

Install Cosmos as a Docker Container

Installation is simple using Docker:

sudo docker run -d --network host  --privileged --name cosmos-server -h cosmos-server --restart=always -v /var/run/docker.sock:/var/run/docker.sock -v /var/run/dbus/system_bus_socket:/var/run/dbus/system_bus_socket -v /:/mnt/host -v /var/lib/cosmos:/config azukaar/cosmos-server:latest

DO NOT USE UNRAID TEMPLATES, CASAOS OR PORTAINER STACKS TO INSTALL COSMOS IF YOU DON'T USE the --network host mode. IT WILL NOT WORK PROPERLY. JUST RUN THE DOCKER RUN COMMAND!

IF YOU ARE USING WINDOWS OR MAC OS YOU CANNOT USE THE HOST MODE OF DOCKER WITH DOCKER DESKTOP. Please replace --network host with -p 80:80 -p 443:443 -p 4242:4242/udp or use an alternative software like

You can use Docker-Compose but if you are on mac or windows (so no host mode) without a domain, that will prevent Cosmos from binding ports to itself! (preventing ip:port from working properly)

version: '3.7'
services:
  cosmos-server:
    image: azukaar/cosmos-server:latest
    container_name: cosmos-server
    hostname: cosmos-server
    restart: always
    privileged: true
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
      - /var/run/dbus/system_bus_socket:/var/run/dbus/system_bus_socket
      - /:/mnt/host
      - /var/lib/cosmos:/config
    network_mode: host

if you do not have docker installed, you can first easily install it this way on Linux, or with the official documentation for windows.

Linux command:

curl -fsSL https://get.docker.com | sudo sh

Once installed, simply go to http://your-server-ip and follow the instructions of the setup wizard.

Make sure you expose the right ports (by default 80 / 443). It is best to keep those ports intact, as Cosmos is meant to run as your reverse proxy. Trying to setup Cosmos behind another reverse proxy is possible but will only create headaches.

You also need to keep the docker socket mounted, as Cosmos needs to be able to manage your containers. Don't expect to be able to run this container as non-root.

Compatibility

Cosmos-Server is compatible with AMD64 and ARM64 architectures (both your OS and CPU have to be 64bits). If you are using a Raspberry Pi, you need at least a Raspberry Pi 3 or Zero 2 W. Once again, check you are using a 64bits OS.

Other settings

in this command, -v /:/mnt/host is optional and allow to manage folders from Cosmos, you can remove it if you don't want it but you will have to create your container's bind folders manually.

--privileged is also optional, but it is required if you use hardening software like AppArmor or SELinux, as they restrict access to the docker socket. It is also required for Constellation to work. If you don't want to use it, you can add the following capabilities: NET_ADMIN for Constellation.

You can change the destination folder of the config file by changing the -v /var/lib/cosmos:/config part of the command. You can also change the name of the container by changing the --name cosmos-server part of the command.

Port 4242 is a UDP port used for the Constellation VPN. For HTTP(S) it uses 80/443 by default but this can be changed with the environment variables COSMOS_HTTP_PORT and COSMOS_HTTPS_PORT. (ex. -e COSMOS_HTTP_PORT=8080 -e COSMOS_HTTPS_PORT=8443)

Finally, if you are using Cosmos from one of the countries considered "high risk," you can prevent Cosmos from blocking your IP by adding the following environment variable to your Docker run command: -e COSMOS_SERVER_COUNTRY=IN. Replace "IN" with your country code. The following countries are blocked by default: China (CN), Russia (RU), Turkey (TR), Brazil (BR), Bangladesh (BD), India (IN), Nepal (NP), Pakistan (PK), Sri Lanka (LK), Vietnam (VN), Indonesia (ID), Iran (IR), Iraq (IQ), Egypt (EG), Afghanistan (AF), and Romania (RO). Please note that this choice is neither political nor personal; it is solely based on past attack statistics. If you are from one of these countries and want to use Cosmos, we sincerely apologize for the inconvenience. If you are having issues with this, please contact us on Discord!

You can tweak the config file accordingly. Some settings can be changed before end with env var. See here.

if you are having issues with the installation, please contact us on Discord!

Your first ServApp

In Cosmos, Servapps are the applications running on your server. In reality they represent Docker containers (or mini virtual machines, for complete isolation). They are the building blocks of your server.

You can install them in many ways:

  • From the Cosmos App Store (the Market tab on the left)
  • From the create Servapp form (The Create Servapp button on the servapp tab)
  • From the import compose function (the Import Compose button on the servapp tab)
  • From the command line (using docker CLI)
  • From any other application (ex. Portainer)

Once created, the servapp will appear in the servapp tab. You can then click on it to access its settings.

There is a "New +" button in the URL sub-category of your servapps. that's where you can create new URLs for your servapp. Those URLs will allow you to access your servapp through Cosmos' proxy. Click on it, and you will be greated with a mostly pre-configured form. Check that all is fine, and click on "Create URL" to create your URL. After restart, your URL will appear on the home page.

Licence

Cosmos is using the Apache 2.0 Licence with the Commons Clause 1.0. This is a common clause among open source infrastructure software, such as databases, reverse proxies, etc...

The TL;DR is: You can use it freely. You can also fork it and redistribute it, But you are not allowed to sell it, a derivative or to sell a service based on it (ex. SaaS or PaaS).

Note that you are allowed to use it to host a monetized business website, a blog etc... as long as your business does not involve selling Cosmos or its features.

Backups

Cosmos exports all your containers in a single file in the config folder (by default /var/lib/cosmos), you can use this file to restore your server in case of a crash. You can also use it to migrate your server to another machine.