Cloudomation Installer

Managing on-premise installations is hard. We found that our users have a need for simple tooling that lets them install, update and manage their Cloudomation workspace installations.

This setup script enables Cloudomation on-premise users to install and update Cloudomation on their own, create backups and clean their database.

important

The setup script only backs up files that are modified by the update: configuration, cloudomation binaries, and database content. It doesn't include the OS or git repositories.

In cases where a full machine backup is needed, you need to create it manually.

Human requirements:

• Basic Linux knowledge
• Service account & license file (you get those when you buy a license)
• Having read the Cloudomation docs https://docs.cloudomation.com/

System requirements:

note

For the on-premise system requirements please click here.

Download

release-7

Usage

Introduction

The setup.sh file is your single entry point to either a fresh Cloudomation workspace installation, an update of an existing workspace installation or to perform database cleanups and licensing tasks.

Flag	Description
-d | --directory DIR	Where Cloudomation should be installed. Defaults to ./cloudomation
-v | --verbose	Enable verbose logging, provides additional output. Useful for debugging
--vacuum	Vacuum the postgresql database Cloudomation uses
-h | --help	Display help in the terminal

New Installation

To install a fresh Cloudomation workspace installation first extract the zip file. Place your serviceaccount.json and license.yml file in the same directory as setup.sh. Open a terminal in this directory and run ./setup.sh. Set the desired installation directory with -d flag. If no flag is passed, the default value ./cloudomation is used.

Most configuration values are set to reasonable defaults. Still, you will be prompted for the following settings:

Setting	Description
ORGANIZATION_NAME	Name of your organization
WORKSPACE_NAME	Name of your workspace. Useful if you want to create multiple workspaces.
BOOTSTRAP_USER	An email address. An invite will be sent to this address. The user will be able to set a password and login to Cloudomation.
SMTP_HOST	Hostname of your SMTP server
SMTP_PORT	Port of your SMTP server
SMTP_USE_TLS	Whether or not to use TLS for SMTP

Install self-signed certificate in browser

After the installation is done, you will need to install the self-signed HTTPS certificate in your browser as an authority. The certificate cert.crt is located in the Cloudomation root directory.

Install cert in Chrome

Install cert in Firefox

Install cert in Brave

Your Cloudomation workspace is now ready for action! 🎉🎉

Per default it is reachable via https://localhost

Change Configuration

If you want to change any settings (wether pre-defined or user-defined), edit setup.yml and run setup.sh again. A diff editor will open, enabling you to control which values should be used. The documentation for imediff is available here. Press h for help.

Upgrade Installation

warning

Before upgrading to a new major version please review the Release Notes as sometimes manual steps are required.

warning

It is generally a good idea to make sure that your processes don't use deprecated features. This becomes especially important when upgrading to a new major version as deprecated features might get removed in newer versions. See here how you can easily find deprecation notes in your workspace.

note

The installer can only upgrade Cloudomation workspace installations which were previously installed using the installer. Upgrading from manual installations (pre Version 6) requires additional steps as described in Migrate from a manual installation.

To upgrade an existing workspace installation first download the new version of the installer from above. Extract the zip file. Open a terminal in this directory and run ./setup.sh.

The installer will prompt you for new or modified configurations and then upgrade and restart the Cloudomation workspace.

Migrate from a manual installation

If you are currently operating a Cloudomation workspace which was not installed using the Cloudomation installer the automatic upgrade does not work. There are two options:

1. Keep the old workspace installation running and create a second workspace installation with the Cloudomation installer. Migrate content and remove the old workspace installation. This is the recommended approach when you are currently using the Git Integration to synchronize Cloudomation content from a git repository.
2. Create a new workspace installation with the Cloudomation installer. Shut down the new installation and copy the database folder from the old installation to the new installation. Start the new installation. The workspace will perform any required database migration steps.

Migrate using Git Integration

This method creates a fresh empty new Cloudomation installation. The Git Integration is used to synchronize your resources into the new Cloudomation installation.

warning

Using this method any content which is not in your git repository will not be migrated to the new Cloudomation installation. This includes all activities, like executions, and resources which were manually created in the Cloudomation workspace.

Please follow the steps outlined below:

1. Make a backup of your old Cloudomation installation.

2. Change the ports of the old Cloudomation installation

   The old Cloudomation installation must be modified to be accessible via a different port. Stop the old installation by running docker-compose down in the old installation folder. Modify docker-compose.yml and change the ports of the "ingress" service:

   # before
   ingress:
     ports:
       - "80:80"
       - "443:443"
   # after
   ingress:
     ports:
       - "8080:80"
       - "8443:443"

3. Start the old Cloudomation installation

   Run docker-compose up -d in the old installation folder to start the old installation. Verify that the processes successfully start and make sure you can log in to your old installation.

4. Create your new Cloudomation installation by following the steps described in New Installation.

5. Log into your new Cloudomation installation and setup the Git Integration.

6. Verify that all resources which are required for your use case are successfully synced to your new Cloudomation installation.

   tip

   If your old Cloudomation installation contained resources which were manually created and not in your git repository they will be missing from the new installation. This is a good chance to identify such resources and the perfect time to add them to your git repository.

7. Test your use cases in the new Cloudomation installation. If needed, you can keep the old Cloudomation installation running in parallel for several days. Once you are confident that the new installation meets your requirements the old installation can be deleted.

   warning

   When activating a use case in the new installation it should at the same time be disabled in the old installation.

note

Using this method it is easily possible to switch back to the old Cloudomation installation at any time should any troubles arise.

Migrate by Copying the Database Folder

1. Make a backup of your old Cloudomation installation.

2. Stop the old Cloudomation installation by running docker-compose down in the old installation folder.

3. Create your new Cloudomation installation by following the steps described in New Installation.

4. Stop the new Cloudomation installation by running docker-compose down in the new installation folder.

5. Delete the pgdata directory in your new installation folder.

   warning

   Make sure you delete the pgdata directory of your new Cloudomation installation.

6. Copy the pgdata directory of your old Cloudomation installation to the new installation folder.

   note

   If you completed a full backup of your old installation (including the pgdata folder) it may be faster to move the pgdata folder to the new installation.

7. Start the new Cloudomation installation.

   Check the logs of the Cloudomation workspace container for successful database migration steps.

8. Test your use cases in the new Cloudomation installation.

Additional Tools

The setup script comes with one additional utility for managing your Cloudomation installation.

vacuum postgresql

This executes postgresql's internal garbage-collection feature, which reclaims space that is not in use by the database anymore. For performance reasons, this dead-space is not reclaimed while the database is running. Further information: https://www.postgresql.org/docs/current/sql-vacuum.html

The --vacuum flag safely shuts down Cloudomation, executes the vacuum command and restarts all services.