Customer Deployment
===================

This guide covers how customers deploy Scaleout Edge on their own infrastructure — either on a server they already manage, or on a cloud provider (AWS or GCP) provisioned via Terraform.

In both cases the starting point is a **release bundle**: a self-contained archive of deployment scripts and a pre-built Docker Compose configuration, distributed through the Scaleout Harbor registry.

.. contents:: On this page
   :local:
   :depth: 1

----

Prerequisites
-------------

A Harbor robot account (username and password) is required for both deployment paths.
Your Scaleout representative will provide these credentials.

**Compose deployment (on-premise)**

- Linux or macOS with Bash 4+ (on Windows use WSL2)
- `Docker Engine 24+ <https://docs.docker.com/engine/install/>`_ with the Compose plugin
- Python 3.8+

**Cloud deployment (Terraform)**

- `Terraform 1.0+ <https://developer.hashicorp.com/terraform/install>`_

----

Step 1: Install ORAS
--------------------

Release bundles are stored as OCI artifacts on Harbor. You need the `ORAS CLI <https://oras.land>`_ to pull them.

.. tab-set::

   .. tab-item:: macOS

      .. code-block:: bash

         brew install oras

   .. tab-item:: Linux (amd64)

      .. code-block:: bash

         VERSION=$(curl -fsSL https://api.github.com/repos/oras-project/oras/releases/latest \
             | python3 -c "import sys,json; print(json.load(sys.stdin)['tag_name'].lstrip('v'))")
         curl -LO "https://github.com/oras-project/oras/releases/download/v${VERSION}/oras_${VERSION}_linux_amd64.tar.gz"
         tar -zxf "oras_${VERSION}_linux_amd64.tar.gz" oras
         sudo mv oras /usr/local/bin/
         rm "oras_${VERSION}_linux_amd64.tar.gz"

   .. tab-item:: Windows

      .. code-block:: powershell

         winget install -e --id ORASProject.ORAS

Verify:

.. code-block:: bash

   oras version

----

Step 2: Authenticate to Harbor
-------------------------------

Log in with your Harbor robot account. Credentials are stored in ``~/.docker/config.json`` and reused for subsequent commands.

.. code-block:: bash

   oras login harbor.scaleoutsystems.com \
     --username 'robot$<your-robot-account>' \
     --password '<your-token>'

----

Step 3: Pull the release bundle
--------------------------------

Pull the release bundle for your version. Replace ``vX.Y.Z`` with the version provided by your Scaleout representative.

.. code-block:: bash

   oras pull harbor.scaleoutsystems.com/scaleout/scaleout:vX.Y.Z

This writes a ``scaleout-vX.Y.Z.tar.gz`` tarball to the current directory. Extract it:

.. code-block:: bash

   tar -xzf scaleout-vX.Y.Z.tar.gz
   cd scaleout-vX.Y.Z/

To list all available versions:

.. code-block:: bash

   oras repo tags harbor.scaleoutsystems.com/scaleout/scaleout

----

Deployment Option A: Compose (on-premise or own server)
--------------------------------------------------------

Use this path when you have a Linux server or VM that you manage directly.

**Authenticate to the container registry**

The compose deployment pulls pre-built images from Harbor. Log in with Docker using the same credentials:

.. code-block:: bash

   docker login harbor.scaleoutsystems.com \
     --username 'robot$<your-robot-account>' \
     --password '<your-token>'

**Generate runtime configuration**

.. code-block:: bash

   ./deploy/setup.sh <hostname> [OPTIONS]

Replace ``<hostname>`` with the domain or IP address where Scaleout will be reachable (e.g. ``scaleout.mycompany.com`` or ``192.168.1.100``).

Common options:

.. list-table::
   :header-rows: 1
   :widths: 40 60

   * - Option
     - Description
   * - ``--enable-https``
     - Enable HTTPS (requires TLS certificates)
   * - ``--disable-signup``
     - Prevent new users from self-registering
   * - ``--google-client-id / --google-client-secret``
     - Enable Google OAuth
   * - ``--microsoft-client-id / --microsoft-client-secret``
     - Enable Microsoft OAuth

Run ``./deploy/setup.sh --help`` for the full option list.

**Start services**

.. code-block:: bash

   ./deploy/compose.sh up

The platform is accessible at ``http://<hostname>`` once all containers are healthy.

**Upgrading**

Download and extract the new release bundle alongside your existing deployment. The ``runtime/`` directory (which holds secrets and generated config) is preserved between upgrades.

.. code-block:: bash

   oras pull harbor.scaleoutsystems.com/scaleout/scaleout:vX.Y.Z
   tar -xzf scaleout-vX.Y.Z.tar.gz
   cd scaleout-vX.Y.Z/
   ./deploy/setup.sh <hostname>
   ./deploy/compose.sh up

----

Deployment Option B: Cloud (AWS or GCP via Terraform)
------------------------------------------------------

Use this path to provision a cloud VM automatically. The Terraform scripts are included in the release bundle under ``infrastructure/``.

The VM bootstraps itself: Terraform creates the instance and passes a startup script that pulls the release bundle from Harbor and runs the deployment — no manual SSH required.

**Configure your deployment**

Copy the example variables file for your cloud provider and fill in your values:

.. tab-set::

   .. tab-item:: GCP

      .. code-block:: bash

         cd infrastructure/gcp/
         cp terraform.tfvars.example terraform.tfvars

   .. tab-item:: AWS

      .. code-block:: bash

         cd infrastructure/aws/
         cp terraform.tfvars.example terraform.tfvars

Open ``terraform.tfvars`` and set at minimum:

.. code-block:: hcl

   domain          = "scaleout.mycompany.com"
   harbor_username = "robot$<your-robot-account>"
   harbor_password = "<your-token>"

``release_bundle_ref`` is pre-filled with the correct version. Replace the Harbor credential placeholders with the values provided by your Scaleout representative.

See ``terraform.tfvars.example`` for the full list of optional settings (OAuth providers, HTTPS, SSH access, system admin bootstrap).

**Apply**

.. code-block:: bash

   terraform init
   terraform apply

Terraform provisions the VM, waits for the startup script to complete, and prints the application URL when done.

**Upgrading**

To upgrade, update ``release_bundle_ref`` in ``terraform.tfvars`` to the new version and run:

.. code-block:: bash

   terraform apply