Installation

Download the sources from the official website

Once started the installation interface will be available on the server.
Open your browser and navigate to https://<your.server.address>. Access is only available using server name to enable name resolution, not via IP address.

Things to consider when running locally

CloudCompose can be installed on a local network, for example, within your home network, on your own computer, or in WSL under Windows. In these cases, you are responsible for managing the name resolution of your applications.

Depending on your setup, you may need to manually resolve the public URLs for application subdomains. Typically, this is done by mapping the URLs to your server's IP address using one of the following methods:

• Edit the /etc/hosts of your computer manually
• Use the Host File Editor of PowerToys or similar apps to do the same
• Extend the DNS whitelists of either your internet router or any adblocking software in charge like Adguard or PiHole

During the initial setup, you need to provide the credentials for an administrative user account as well as the base domain name for your services.

All applications launched by CloudCompose will be accessible publicly at https://<application-name>.<your.base.domain>.

The simplest method to secure your applications is by using a wildcard certificate for your base domain—refer to the configuration section for details.

Once the initial setup is completed, you will be forwarded to the login. This will bring you to the main CloudCompose interface where you can manage applications, users, permissions, as well as upload certificates and monitor environment statistics.

Configuration

Before you begin running applications, it is recommended to provide an SSL certificate. This helps prevent your users from seeing browser warnings about security risks

CloudCompose applications operate over HTTPS. You can upload one or more certificate files, which will be utilized by HAProxy when delivering the applications

To upload a certificate, navigate to the SSL Certificates section in the main menu. There, click the "Upload Certificate" button and select a local certificate file, typically with a *.pem extension. When uploading from a Windows PC, be sure that the file name does not start with a dot or asterisk, as we got reports of users having issues with certifcate file name starting with special characters.

Any file you upload will instantly be listed among the available certificates, along with details such as the expiry date and the domains it covers.

Manage Applications

To launch and manage applications, navigate to the Applications section in the main menu.

You will see two tabs that distinguish between installed applications and available ones. To launch an application, go to the Installed Applications tab. Applications that are currently running are marked with a green "healthy" badge. Click the "Open" button to access the application in a new tab.

Manage Applications as an administrator

Open the available applications tab to view a list containing details about each application. From there, you can review information such as a summary of its functionality and any system requirements.

When you want to add an application to your environment, click the corresponding "Install" button. Confirm the intent to install in the upcoming dialog. The following steps will be carried out to set up the application. The container images will be transferred, configured, and started. Depending on the application, post-installation processes may be required. Please be patient until the installation is complete.

To remove an application from your environment, click the "Stop" button in the list of installed applications. A stopped application does not use any system resources such as CPU or RAM. However, the stored data remains available, allowing users to continue working as usual after restarting the application. To permanently delete the data and free up disk space, the stopped application must be removed by clicking the "Delete" button.

User Management

CloudCompose distinguishes between two user groups: administrators and regular users. All users log in to CloudCompose through the same interface, but only see the content and options relevant to their role.

To perform user management tasks such as adding, removing, or modifying users, administrators access the Users section from the main menu.

To add a new user, click the "Add User" button in the top-right corner. A dialog will appear requesting an email address and a username, both of which must be unique across all users and cannot be changed afterwards. Furthermore set whether the new user should be a regular user or administrator. The role can be changed later on.

To remove a user, click the “Delete” button. Please note that the deleted user will permanently lose access permissions to the application, even if the account is recreated.

Each new user is assigned a random password by default. To define a custom initial password, click the “(Re)Set Password” button. After logging in, the user can update their password at any time via the user dropdown menu in the top-right corner of the header bar.

Single Sign On With Keycloak

While local user and session management may be adequate for small-scale or edge deployments, enterprise-grade infrastructures generally require a centralized identity and access management (IAM) solution.

CloudCompose supports Keycloak as identity provider, offering direct or mitigated integration of OpenID Connect, OAuth, and LDAP. Keycloak is not included in CloudCompose but must be installed seperately.

For more information about Keycloak integration, please get in touch with us or refer to examples in the source repository of CloudCompose

Permissions

By default, only the account administrator has access to newly installed applications. To grant access to standard users, navigate to the "Permissions" section in the main menu. You will find two tabs for the directions to grant permissions: Either allow or deny access to installed applications per user. Or allow or deny access by users for a single application.

Changes in the permissions will take effect instantly.

Monitoring

In order to monitor system ressource consumption, navigate to the "Statistics" section in the main menu.

You can monitor the current consumption of CPUs, memory, disk space - aggregated and per installed application.

Backups

Cloudcompose does not support any user interface for backups right now.

You can use built-in backups capabilities of Docker or use custom tools. Container volumes are stored in the data/manager/container-volumes directory in your CloudCompose main folder. To further delve into the topic of backups, use our consulting services.

Add Applications

When you want to add an application to your CloudCompose environment that is not available out-of-the-box, you will have to add an integration to the source code.

Custom Integrations are placed in the folder named data/manager/integrations of your CloudCompose installation. Every integration resides in it's own subdirectory, the pattern for the directory name is <appname>__<version>, e.g. uptime-kuma__1.0.
See the minimal structure of any integration source code below:

The main file of any integration is the index.mjs, where a class Integration is defined. See a sample below. The integration is free to implement custom logic which can be imported to index.mjs.

export default class Integration { get config() { return { name: "Name of Your App", tech_name: "name-of-your-app", version: "1.0", url: "Public documentation website of integrated application", color: "#ff0000", img: "data:image/png;base64,...", // Auth type must be one of: "basic-auth", "cookie", "built-in", "none" default_auth_method: "cookie", // CloudCompose will generate passwords per application and user and support automatic login with_local_passwords: true, // these URLs are NOT checked by the proxy...and can be fetched without any login auth_exception_urls: [ "/manifest.json", ... ], // Optional web route to run for postinstall (AFTER creating and starting the container) post_install_route: "/setup", code_injection_urls: [ { "type": "install", // or login "patterns":["/register"], "replaceString": `... replaced code ...`, "code": `... replacement code ...` } ] } } // Returns a set of generated values which can be used in getContainers, see below generatedVars(tenant){ return { "DB_PASS": {length:20, specialChars:''} } } // Returns a container definition much like docker-compose.yml getContainers(tenant, generatedVars, local_app_passwords) { return { // the container-name must be unique and starts with cc-app-* by convention "container-name":{ "image": "docker-image-name-or-url", "version": "1", "ports": { // declare subdomain property when port is exposed publically 3001: { subdomain: "app-subdomain"} }, "env_params": { // example usage of generated variable DB_PASSWORD: 'GENERATED_VAR:DB_PASS' } volumes: { "data": { internalPath: "/app/data", type: "rw" } } } } } // Place to initialize things. // CONTEXT contains reference to keycloak and runCommand() method constructor(CONTEXT) { } // The following callback can be used to perform actions // in the context of the application whenever // changes in CloudCompose are performed // Callback is executed when app is installed async postinstall(tenant, data) { } // Callback is executed when user is added or altered async upsertUsers(tenant, data, generated_vars, users) { // Callback is executed then user with permission is deleted async deleteUsers(tenant, data, generated_vars, users) { } // Callback is executed when permissions change async updatePermissions(enant, data, generated_vars, users) { } }

The locales.json contains descriptive text for the integration. Those values will be displayed in the "Applications" section in CloudCompose. Per default the CloudCompose user interface supports the following languages: English, German, Spanish, French, Italian, Polish.

{ "en": { "slogan": "Best application ever", "description": "This will be a description for the best app ever." }, "de": { "slogan": "", "description": "" }, "es": { "slogan": "", "description": "" }, "fr": { "slogan": "", "description": "" }, "it": { "slogan": "", "description": "" }, "pl": { "slogan": "", "description": "" } }