Engine 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 Engine workspace installations.

This setup script enables Engine on-premise users to install and update Engine 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 Engine docs https://docs.cloudomation.com/

System requirements:

note

For the on-premise system requirements please click here.

Download

release 9

Usage

Introduction

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

Flag	Description
-h | --help	Display help in the terminal
-d | --directory DIR	Where Engine should be installed. Defaults to ./cloudomation
-v | --verbose	Enable verbose logging, provides additional output. Useful for debugging
--cert-mode	Which certificate to use. one of selfsigned (default), existing, or letsencrypt
--cert <crt> <key>	Specify path to existing certificate and key. required for cert-mode existing
--interactive	Run interactive (default)
--no-interactive	Run without any interactive prompts
--setup-database	Create databases & database users (default)
--no-setup-database	Do not attempt to create databases & database users
--provide-database	Provide a postgresql service (default).
--no-provide-database	Do not provide a postgresql service. if set, connection parameters for an external database must be provided in .env.
--vacuum	Vacuum the postgresql database Engine uses
--save-logs	Collect logs, create a zip containing the logs and exit
--workspaces	The number of workspace workers, defaults to 4
--database-remove-config	Remove one or more workspace configuration keys from the database

New Installation

To install a fresh Engine 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 Engine.
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 Engine root directory.

Install cert in Chrome

Install cert in Firefox

Install cert in Brave

Your Engine 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 Engine 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 Engine workspace.

Migrate from a manual installation

If you are currently operating an Engine workspace which was not installed using the Engine 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 Engine installer. Migrate content and remove the old workspace installation. This is the recommended approach when you are currently using the Git Integration to synchronize Engine content from a git repository.
2. Create a new workspace installation with the Engine 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 Engine installation. The Git Integration is used to synchronize your resources into the new Engine installation.

warning

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

Please follow the steps outlined below:

1. Make a backup of your old Engine installation.

2. Change the ports of the old Engine installation

   The old Engine 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 Engine 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 Engine installation by following the steps described in New Installation.

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

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

   tip

   If your old Engine 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 Engine installation. If needed, you can keep the old Engine 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 Engine installation at any time should any troubles arise.

Migrate by Copying the Database Folder

1. Make a backup of your old Engine installation.

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

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

4. Stop the new Engine 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 Engine installation.

6. Copy the pgdata directory of your old Engine 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 Engine installation.

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

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

Additional Tools

The setup script comes with one additional utility for managing your Engine 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 Engine, executes the vacuum command and restarts all services.