Skip to content

Deploying the Apheris Hub🔗

You can deploy the Apheris Hub either as a container or to an AWS EC2 instance using a CloudFormation template.

Requirements:

For the Co-Folding application and in particular OpenFold3, there are a few resource requirements to consider:

  • Modern GPU with at least 48GB GPU memory (in AWS, the G6e is an example of a cost-effective machine that supports OpenFold3)
  • At least 300GB of disk space

Additionally, you need the Apheris Hub API Key to pull the Co-Folding Docker images (request here)

Simple: Pre-built Container🔗

The pre-built Docker image is the simplest way to run the Apheris Hub. Using the pre-built image is the most flexible deployment option and allows for deploying wherever you or your team typically operate.

The basic steps include:

  • Create the directories for storing state (SQLite database), input and output data
  • Create a Docker network or use an existing one
  • Update the docker run command
    • --network - adjust the network name if you choose a different docker network
    • --env=APH_HUB_API_KEY - insert the Apheris Hub API Key that was provided to you by Apheris
    • Version of the image to the current Apheris Hub version i.e., quay.io/apheris/hub:0.2.0 (see Quay for the latest version)
  # Folders for persisting Apheris Hub state, inputs and outputs
  mkdir -p $HOME/apheris-hub/{db,input,output}
  chmod -R g+s $HOME/apheris-hub

  # Create a Docker network
  docker network create apheris-hub

  # Run the Apheris Hub container
  docker run \
    --name=apheris-hub \
    --detach \
    --rm \
    --network=apheris-hub \
    --platform=linux/amd64 \
    --user=$(id -u):$(stat -c '%g' /var/run/docker.sock) \
    --publish=127.0.0.1:8080:8080 \
    --mount=type=bind,src=$HOME/apheris-hub,dst=$HOME/apheris-hub \
    --mount=type=bind,src=/var/run/docker.sock,dst=/var/run/docker.sock \
    --env=APH_HUB_API_KEY=KEY_PROVIDED_BY_APHERIS \
    --env=APH_HUB_INPUT_ROOT_DIRECTORY=$HOME/apheris-hub/input \
    --env=APH_HUB_OUTPUT_ROOT_DIRECTORY=$HOME/apheris-hub/output \
    --env=APH_HUB_DATABASE_FILE_NAME=$HOME/apheris-hub/db/hub.db \
    quay.io/apheris/hub:0.2.0

  # Folders for persisting Apheris Hub state, inputs and outputs
  mkdir -p $HOME/apheris-hub/{db,input,output}
  chmod -R g+s $HOME/apheris-hub

  # Create a Docker network
  docker network create apheris-hub

  # Run the Apheris Hub container
  docker run \
    --name=apheris-hub \
    --detach \
    --rm \
    --network=apheris-hub \
    --platform=linux/amd64 \
    --user=0 \
    --publish=127.0.0.1:8080:8080 \
    --mount=type=bind,src=$HOME/apheris-hub,dst=$HOME/apheris-hub \
    --mount=type=bind,src=/var/run/docker.sock,dst=/var/run/docker.sock \
    --env=APH_HUB_API_KEY=KEY_PROVIDED_BY_APHERIS \
    --env=APH_HUB_INPUT_ROOT_DIRECTORY=$HOME/apheris-hub/input \
    --env=APH_HUB_OUTPUT_ROOT_DIRECTORY=$HOME/apheris-hub/output \
    --env=APH_HUB_DATABASE_FILE_NAME=$HOME/apheris-hub/db/hub.db \
    quay.io/apheris/hub:0.2.0

After starting the container, the Hub will be available at localhost:8080.

Troubleshooting🔗

Error: Bind for 0.0.0.0:8080 failed: port is already allocated🔗

This error means that another process on your machine is already using port 8080.

You can map a different local port (e.g. 8081) to the container’s internal 8080 by adjusting in the docker run command:

  --publish=127.0.0.1:8081:8080

Cloud: AWS EC2 instance using a CloudFormation template🔗

The CloudFormation template provides a complete setup for deploying the Apheris Hub to a single instance on AWS. This option simplifies deploying into a cloud environment but assumes technical familiarity with AWS and an account with the necessary permissions.

There are some required AWS permissions needed in order to be able to use AWS CloudFormation. The following example policy has the needed permissions required to use CloudFormation.

Example AWS Policy for using CloudFormation 
{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "CloudFormation:CreateStack",
        "CloudFormation:UpdateStack",
        "CloudFormation:DeleteStack",
        "CloudFormation:DescribeStacks",
        "CloudFormation:DescribeStackResources",
        "CloudFormation:DescribeStackEvents",
        "CloudFormation:GetTemplate"
      ],
      "Resource": "*"
    },
    {
      "Effect": "Allow",
      "Action": [
        "ec2:RunInstances",
        "ec2:TerminateInstances",
        "ec2:CreateSecurityGroup",
        "ec2:DeleteSecurityGroup",
        "ec2:AuthorizeSecurityGroupIngress",
        "ec2:AuthorizeSecurityGroupEgress",
        "ec2:CreateLaunchTemplate",
        "ec2:DeleteLaunchTemplate",
        "ec2:CreateTags",
        "ec2:DescribeImages",
        "ec2:DescribeInstances",
        "ec2:DescribeSecurityGroups",
        "ec2:DescribeSubnets",
        "ec2:DescribeVpcs",
        "ec2:DescribeKeyPairs",
        "ec2:DescribeLaunchTemplates"
      ],
      "Resource": "*"
    },
    {
      "Effect": "Allow",
      "Action": [
        "iam:CreateRole",
        "iam:DeleteRole",
        "iam:CreateInstanceProfile",
        "iam:DeleteInstanceProfile",
        "iam:AddRoleToInstanceProfile",
        "iam:RemoveRoleFromInstanceProfile",
        "iam:AttachRolePolicy",
        "iam:DetachRolePolicy",
        "iam:PassRole",
        "iam:GetRole",
        "iam:GetInstanceProfile"
      ],
      "Resource": "*"
    },
    {
      "Effect": "Allow",
      "Action": [
        "ssm:GetParameter"
      ],
      "Resource": "arn:aws:ssm:*:*:parameter/aws/service/deeplearning/ami/x86_64/base-oss-nvidia-driver-gpu-amazon-linux-2023/latest/ami-id"
    }
  ]
}

The CloudFormation deployment allows for a simple wizard style setup and flexibility based on your environment. See below for more information such as configuring based on your network visibility requirements or accessing via SSM or SSH.

Get Started🔗

  1. Log in to the AWS account where the Apheris Hub will be deployed
  2. Use this link to access the CloudFormation Template

You should see a create stack form similar to the following:

You should see a create stack form similar to the following: Screenshot of the AWS CloudFormation Quick create stack page showing the setup for launching an Apheris Hub EC2 instance. The form includes fields for the template URL, stack name, API key, VPC ID, subnet ID, SSH key pair name, public IP association, and ingress CIDR. The environment is a web interface with a neutral, professional tone. The visible text includes instructions and example values such as apheris-co-folding for the stack name, YOUR-KEY-HERE for the API key, and vpc-062a35045937c8a8 for the VPC ID.

Configuration🔗

For deployment, you will need at least:

  • A valid Apheris Hub API Key (parameter ApherisApiKey)
  • An appropriate VPC setup (parameters VpcId and SubnetId)
    • The VPC setup must allow outbound traffic to the Internet to pull model docker images and enable AWS SSM access to the instance.

Connect🔗

You can connect to the Apheris Hub via:

  • AWS SSM
  • OpenSSH
  • Direct HTTP access

Please read carefully through Tunneling access over SSM, Tunneling access over SSH, and Direct HTTP Access via the internet to decide on the best way for you to access the Hub.

Tunneling access over SSM🔗

To tunnel from your local machine with the AWS CLI, you will need the Session Manager plugin for the AWS CLI. Follow the steps in the AWS documentation if you need to set the plugin up.

Note, you will now start a session with your running instance. This requires the AWS Session Manager plugin, see the AWS CLI documentation for how-to install.

You are now ready to tunnel into the instance and expose the frontend via port 8080 (or your preferred port). This can be done with a simple command, which is easily found in the outputs of the CloudFormation template (shown below).

Screenshot of the AWS CloudFormation Outputs tab displaying two output keys for a deployed EC2 instance. The SSMCommand key provides an AWS CLI command to start a port forwarding session to the instance on port 8080.

You can also update and use the following command:

aws ssm start-session --target <instance_id> --document-name AWS-StartPortForwardingSession --parameters '{"portNumber":["8080"],"localPortNumber":["8080"]}'

After executing, you should receive output similar to the following:

Starting session with SessionId: support@apheris.com
Port 8080 opened for sessionId support@apheris.com.
Waiting for connections...

Connection accepted for session [support@apheris.com]

Visit localhost:8080 to access the Apheris Hub via the tunnel.

Tunneling access over SSH🔗

You will need to be able to connect to the instance from your local machine. Consider doing this via a VPN, jump-host, or similar.

As an alternative, you can deploy the instance to a public subnet and assign it a public IP address. The CloudFormation template requires you to explicitly provide a source CIDR range to open ingress from (AllowIngressFromCidr).

You can tunnel from your local machine with SSH:

ssh -i <path_to_the_private_key_on_your_machine> ec2-user@<instance_ip> -L 8080:localhost:8080

A complete command is also in the SSHCommand CloudFormation stack output.

Visit localhost:8080 to access the Apheris Hub via the tunnel.

Direct HTTP Access via the Internet🔗

Note

This option exposes the application to the public Internet. This is considered insecure. This deployment method is only recommended for non-sensitive evaluation or when used behind an Enterprise proxy.

You can also restrict access to the Apheris Hub to one specific machine by allowing only its IP address using a /32 CIDR suffix (see AllowIngressFromCidr below).

In order to set up direct HTTP access via the Internet:

  • Deploy the instance to a public subnet (the SubnetId parameter)
  • Assign it a public IP address (the AssociatePublicIp parameter needs to be true)
  • Provide a CIDR range to restrict ingress to (the AllowIngressFromCidr parameter)

Visit the URL in the UiUrl CloudFormation stack output to access the Apheris Hub.

Source: Build from Source🔗

You can also build the Apheris Hub and the Co-Folding application from source. For access to the source code, contact us at support@apheris.com.