Deploying Gel to AWS​

.md

Copy page

CloudFormation Web Portal​

Click here to start the deployment process using CloudFormation portal and follow the prompts. You'll be prompted to provide a value for the following parameters:

• DockerImage: defaults to the latest version (geldata/gel), or you can specify a particular tag from the ones published to Docker Hub.

• InstanceName: ⚠️ Due to limitations with AWS, this must be 22 characters or less!

• SuperUserPassword: this will be used as the password for the new Gel instance. Keep track of the value you provide.

Once the deployment is complete, follow these steps to find the host name that has been assigned to your Gel instance:

1. Open the AWS Console and navigate to CloudFormation > Stacks. Click on the newly created Stack.

2. Wait for the status to read CREATE_COMPLETE—it can take 15 minutes or more.

3. Once deployment is complete, click the Outputs tab. The value of PublicHostname is the hostname at which your Gel instance is publicly available.

4. Copy the hostname and run the following command to open a REPL to your instance.

   Copy

   $ 

   gel --dsn gel://admin:<password>@<hostname> --tls-security insecure

   Gel x.x
   Type \help for help, \quit to quit.
   gel>

To make changes to your Gel deployment like upgrading the Gel version or enabling the UI you can follow the CloudFormation Updating a stack instructions. Search for ContainerDefinitions in the template and you will find where Gel's environment variables are defined. To upgrade the Gel version specify a docker image tag with the image name geldata/gel in the second step of the update workflow.

CloudFormation CLI​

Alternatively, if you prefer to use AWS CLI, run the following command in your terminal:

$ 
  
  
  
  
  

aws cloudformation create-stack \
  --stack-name Gel \
  --template-url \
    https://gel-deployment.s3.us-east-2.amazonaws.com/gel-aurora.yml \
  --capabilities CAPABILITY_NAMED_IAM \
  --parameters ParameterKey=SuperUserPassword,ParameterValue=<password>

Obtaining connection parameters​

Your connection requires the following components:

• Host: The PublicHostname value from the CloudFormation Stack's Outputs tab.

• Port: 5656 (the default Gel port)

• Username: admin (the default superuser)

• Password: The SuperUserPassword you specified during deployment

• Branch: main (the default branch)

Construct the DSN using these values:

$ 

GEL_DSN="gel://admin:<password>@<hostname>:5656"

Obtaining the TLS certificate​

To connect securely, your application needs the server's TLS certificate. For self-signed certificates, you can retrieve the certificate by connecting to the instance and extracting it:

$ 
  

gel --dsn $GEL_DSN --tls-security insecure \
  query "SELECT sys::get_tls_certificate()"

Store this certificate and provide it to your application via the GEL_TLS_CA or GEL_TLS_CA_FILE environment variable.

Using in your application​

Set these environment variables where you deploy your application:

GEL_DSN="gel://admin:<password>@<hostname>:5656"
# For self-signed certificates:
GEL_CLIENT_TLS_SECURITY=insecure
# Or with a proper TLS certificate:
GEL_TLS_CA="<certificate content>"

Gel's client libraries will automatically read these environment variables.

Local development with the CLI​

To make your remote instance easier to work with during local development, create an alias using gel instance link.

$ 
  
  
  
  

gel instance link \
  --dsn $GEL_DSN \
  --non-interactive \
  --trust-tls-cert \
  my_aws_instance

You can now refer to the remote instance using the alias my_aws_instance. Use this alias wherever an instance name is expected:

$ 

gel -I my_aws_instance

Gel x.x
Type \help for help, \quit to quit.
gel>

Or apply migrations:

$ 

gel -I my_aws_instance migrate