Workspace deployment overview

ACE has 2 ways of deploying workspace to runtime server - MongoDB (recommended) or Docker based deployment.

Migration to MongoDB deployment is described here.

Please note if using scheduler functionalty in ACE. Schedules require a separate deployment step as they are not installed by the workspace deployment step. This step is described below for both MongoDB and Docker deployment.

MongoDB deployment

MongoDB deployment is the recommended way of deploying workspaces to runtime server.

In this approach, the workspace is stored in MongoDB and runtime server reads the workspace from MongoDB.

This approach allows to do deployments without restarting ACE runtime as ACE automatically detects changes in workspace and loads the new workspace.

Workspace can be deployed using Deployment API or ACE CLI by providing either Git repository details or workspace directly as folder or .zip file.

See few examples below.

Runtime server deployment

Runtime server is the main service which exposes APIs defined in workspace.

Sample deployment via API from git repository:

curl -f -X POST <deployment-service>/deploy/workspace/git \
-H "Content-Type: application/json" \
-d '{"repository":"<git-url>", "token":"<git-token>","branch":"<git-branch>","repositoryWorkspacePath":"<ws-path>" }'

Or sample deployment via CLI from local directory:

ace-cli deploy workspace --folder <ws-location>

Scheduled job deployment

Scheduled jobs are handled by BullMQ which stores data in Redis instance. During deployment existing scheduled jobs are replaced with new ones.

Sample schedule deployment via API from git repository:

curl -f -X POST <deployment-service>/deploy/schedules/git \
-H "Content-Type: application/json" \
-d '{"repository":"<git-url>", "token":"<git-token>","branch":"<git-branch>","repositoryWorkspacePath":"<ws-path>" }'

Or sample schedule deployment via CLI from local directory:

ace-cli deploy schedules --folder <ws-location>

Multiple workspace deployment

ACE provides support for deploying multiple workspaces in 2 ways.

Using deployment APIs:

• Deploy first workspace (it replaces all existing data by default)
• Deploy second workspace with merge=true query parameter

Using CLI merge command:

• Merge workspace in local folder ace-cli merge <from> <to>
• Deploy merged workspace ace-cli deploy workspace --folder <ws-location>

Docker deployment

Docker based approach is to combine ACE runtime and ACE workspace together as one Docker image.

Advantage is ability to deploy same tested combination of ACE runtime and workspace to multiple environments, however in development workflow it results in a lot of Docker images, and it requires service restart to deploy changes.

In practice, this approach works by extending ACE base image and copying ACE workspace data into extended image.

Runtime server deployment

It is necessary to build Docker image with workspace data and deploy it as runtime server.

Sample Dockerfile (assuming src/ace is workspace location):

FROM euadigportalcoredev02acr.azurecr.io/ace-runtime-server:${ACE_VERSION}

COPY src/ace /var/workspace

Scheduled job deployment

Scheduled jobs are handled by the runtime server using the BullMQ library, which stores information about tasks on a Redis instance. During deployment existing scheduled jobs are replaced with new ones.

It is possible to use Deployment API service to deploy scheduled jobs by running it as a one-off Kubernetes job. This approach requires building an extended Docker image with workspace data.

In the following example, the ace-scheduler-deployment image is built and then deployed as a one-off job.

Dockerfile

Sample Dockerfile (assuming src/ace is workspace location) for building the Docker image:

Dockerfile to build 'ace-scheduler-deployment' image

FROM euadigportalcoredev02acr.azurecr.io/ace-deployment-server:${ACE_VERSION}

COPY src/ace /var/workspace

CMD [ "ace-cli", "deploy", "schedules", "--folder", "/var/workspace" ]

Deployment job

Sample deployment to run the image as a one-off job.

Note that the job definition must include environment variables to connect redis for a successful deployment. The minimum configuration is shown in the following example:

Deployment file

apiVersion: batch/v1
kind: Job
metadata:
  name: ace-scheduler-deployment
spec:
  ttlSecondsAfterFinished: 60
  template:
    restartPolicy: Never
    spec:
      containers:
        - name: ace-scheduler-deployment
          image: ace-scheduler-deployment:latest
          env:
            - name: SCHEDULER_REDIS_HOST
              value: "<REDIS_HOST>"
            - name: SCHEDULER_REDIS_PORT
              value: "<REDIS_PORT>"
            - name: SCHEDULER_REDIS_PASSWORD
              value: "<REDIS_PASSWORD>"
            - name: SCHEDULER_REDIS_PREFIX
              value: "bull" # Should match the prefix used in the ace-runtime-server deployment.
                            # If there is none, leave default value.

Multiple workspace deployment

It's possible to deploy multiple workspaces in Docker based approach by merging them in Dockerfile.

Approach is to:

• Copy the first workspace into a folder in container.
• Copy over the other workspace into the same location in container to merge with the first.

Example Dockerfile setup using Docker COPY given two ACE workspaces src/ace-library and src/ace-customer:

Updated dockerfile

FROM euadigportalcoredev02acr.azurecr.io/ace-runtime-server:${ACE_VERSION}

COPY src/ace-library /var/workspace
COPY src/ace-customer /var/workspace
  

The final workspace will be located in /var/workspace.

Multiple workspace deployment (legacy)

Legacy

Since 25.1.0, API file split is mandatory and ace-cli merge command is removed. See instructions above for merging workspace using Docker COPY command.

ACE provides support for deploying multiple workspaces via the ace-cli merge command which is available in the ace-runtime-server service container. The workflow involves:

• Copying the workspaces into the container
• Merging them with ace-cli merge <source> <target>

Read more about the merge command here.

Example Dockerfile setup using the cli command ace-cli merge given two ACE workspaces src/ace-library and src/ace-customer:

Updated dockerfile

FROM euadigportalcoredev02acr.azurecr.io/ace-runtime-server:${ACE_VERSION}

COPY src/ace-library /var/ws/library
COPY src/ace-customer /var/ws/customer

RUN ace-cli merge /var/ws/library /var/workspace && \
    ace-cli merge /var/ws/customer /var/workspace