# Custom Certificate
Source: https://www.aptible.com/docs/core-concepts/apps/connecting-to-apps/app-endpoints/custom-certificate



When an [Endpoint](/docs/core-concepts/apps/connecting-to-apps/app-endpoints/overview) requires a Certificate to perform SSL / TLS termination on your behalf, you can opt to provide your own certificate and private key instead of Aptible managing them via [Managed TLS](/docs/core-concepts/apps/connecting-to-apps/app-endpoints/managed-tls). Start by generating a [Certificate Signing Request](https://en.wikipedia.org/wiki/Certificate_signing_request)(CSR) using [these steps](/docs/how-to-guides/app-guides/generate-certificate-signing-requests). With the certificate and private key in hand:

* Select the appropriate App
* Navigate to Endpoints
* Add an endpoint
* Under **Endpoint Type**, select the *Use a custom domain with a custom certificate* option.
* Under **Certificate**, add a new certificate
* Add the certificate and private key to the respective sections
* Save Endpoint

<Info>Aptible doesn't *require* that you use a valid certificate. If you want, you're free to use a self-signed certificate, but of course, your clients will receive errors when they connect.</Info>

# Format

The certificate should be a PEM-formatted certificate bundle, which means you should concatenate your certificate file along with the intermediate CA certificate files provided by your CA.

As for the private key, it should be unencrypted and PEM-formatted as well.

<Warning>Don't forget to include intermediate certificates! Otherwise, your customers may receive a certificate error when they attempt to connect. However, you don't need to worry about the ordering of certificates in your bundle: Aptible will sort it properly for you.</Warning>

# Hostname

When you use a Custom Certificate, it's your responsibility to ensure the [Custom Domain](/docs/core-concepts/apps/connecting-to-apps/app-endpoints/custom-domain) you use and your certificate match.

If they don't, your users will see certificate errors.

## Supported Keys

Aptible supports the following types of keys for Custom Certificates:

* RSA 1024
* RSA 2048
* RSA 4096
* ECDSA prime256v1
* ECDSA secp384r1
* ECDSA secp521r1


# Custom Domain
Source: https://www.aptible.com/docs/core-concepts/apps/connecting-to-apps/app-endpoints/custom-domain

Learn about setting up endpoints with custom domains

# Overview

Using a Custom Domain with an [Endpoint](/docs/core-concepts/apps/connecting-to-apps/app-endpoints/overview), you can send traffic from your own domain to your [Apps](/docs/core-concepts/apps/overview) running on Aptible.

# Endpoint Hostname

When you set up an Endpoint using a Custom Domain, Aptible will provide you with an Endpoint Hostname of the form `elb-XXX.aptible.in`.

<Tip> The following things are **not** Endpoint Hostnames:
`app.your-domain.io` is your Custom Domain and `app-123.on-aptible.com` is a [Default Domain](/docs/core-concepts/apps/connecting-to-apps/app-endpoints/default-domain). In contrast, this is an Endpoint Hostname: `elb-foobar-123.aptible.in`. </Tip>

You should **not** send traffic directly to the Endpoint Hostname. Instead, to finish setting up your Endpoint, create a CNAME from your own domain to the Endpoint Hostname.

<Info> You can't create a CNAME for a domain apex (i.e. you **can** create a CNAME from `app.foo.com`, but you can't create one from `foo.com`). If you'd like to point your domain apex at an Aptible Endpoint, review the instructions here: [How do I use my domain apex with Aptible?](/docs/how-to-guides/app-guides/use-domain-apex-with-endpoints/overview). </Info>

<Warning>Warning: Do **not** create a DNS A record mapping directly to the IP addresses for an Aptible Endpoint, or use the Endpoint IP addresses directly: those IP addresses change periodically, so your records and configuration would eventually go stale. </Warning>

<Tip>
  If you use Cloudflare in front of an Aptible Endpoint, see [Set Up Cloudflare with Aptible Endpoints](/docs/how-to-guides/app-guides/set-up-cloudflare-with-aptible-endpoints) for the recommended origin and public hostname pattern.
</Tip>

# SSL / TLS Certificate

For Endpoints that require [SSL / TLS Certificates](/docs/core-concepts/apps/connecting-to-apps/app-endpoints/overview#ssl--tls-certificates), you have two options:

* Bring your own [Custom Certificate](/docs/core-concepts/apps/connecting-to-apps/app-endpoints/custom-certificate): in this case, you're responsible for making sure the certificate you use is valid for the domain name you're using.
* Use [Managed TLS](/docs/core-concepts/apps/connecting-to-apps/app-endpoints/managed-tls): in this case, you'll have to provide Aptible with the domain name you plan to use, and Aptible will take care of certificate provisioning and renewal for you.


# Default Domain
Source: https://www.aptible.com/docs/core-concepts/apps/connecting-to-apps/app-endpoints/default-domain



<Warning>Don't create a CNAME from your domain to an Endpoint using a Default Domain. These Endpoints use an Aptible-provided certificate that's valid for `*.on-aptible.com`, so using your own domain will result in a HTTPS error being shown to your users. If you'd like to use your own domain, set up an Endpoint with a [Custom Domain](/docs/core-concepts/apps/connecting-to-apps/app-endpoints/custom-domain) instead.</Warning>

When you create an [Endpoint](/docs/core-concepts/apps/connecting-to-apps/app-endpoints/overview) with a Default Domain, Aptible will provide you with a hostname you can directly send traffic to, with the format `app-APP_ID.on-aptible.com`.

# Use Cases

Default Domains are ideal for internal and development apps, but if you need a branded hostname to send customers to, you should use a [Custom Domain](/docs/core-concepts/apps/connecting-to-apps/app-endpoints/custom-domain) instead.

# SSL / TLS Certificate

For Endpoints that require [SSL / TLS Certificates](/docs/core-concepts/apps/connecting-to-apps/app-endpoints/overview#ssl--tls-certificates), Aptible will automatically deploy a valid certificate when you use a Default Endpoint.

## One Default Endpoint per app

At most, one Default Endpoint can be used per app. If you need more than one Endpoint for an app, you'll need to use Endpoints with a [Custom Domain](/docs/core-concepts/apps/connecting-to-apps/app-endpoints/custom-domain).

## Custom Default Domains

If you cannot use the on-aptible.com domain, or have concerns about the fact that external Endpoints using the on-aptible.com domain are discoverable via the App ID, we can replace `*.on-aptible.com` with your own domain. This option is only available for apps hosted on [Dedicated Stacks](/docs/core-concepts/architecture/stacks#dedicated-stacks). Contact [Aptible Support](/docs/how-to-guides/troubleshooting/aptible-support) for more information.


# gRPC Endpoints
Source: https://www.aptible.com/docs/core-concepts/apps/connecting-to-apps/app-endpoints/grpc-endpoints



<img alt="Image" />

gRPC Endpoints can be created using the [`aptible endpoints:grpc:create`](/docs/reference/aptible-cli/cli-commands/cli-endpoints-grpc-create) command.

<Warning>Like TCP/TLS endpoints, gRPC endpoints do not support [Endpoint Logs](/docs/core-concepts/apps/connecting-to-apps/app-endpoints/https-endpoints/endpoint-logs)</Warning>

# Traffic

gRPC Endpoints terminate TLS traffic and transfer it as plain TCP to your app.

# Container Ports

gRPC Endpoints are configured similarly to [TLS Endpoints](/docs/core-concepts/apps/connecting-to-apps/app-endpoints/tls-endpoints).

The Endpoint will listen for encrypted gRPC traffic on exposed ports and transfer it as plain gRPC traffic to your app over the same port. For example, if your [Image](/docs/core-concepts/apps/deploying-apps/image/overview) exposes port `123`, the Endpoint will listen for gRPC traffic on port `123`, and forward it as plain gRPC traffic to your app [Containers](/docs/core-concepts/architecture/containers/overview) on port `123`.

<Tip>Unlike [TLS Endpoints](/docs/core-concepts/apps/connecting-to-apps/app-endpoints/tls-endpoints), gRPC Endpoints DO provide [Zero-Downtime Deployment](/docs/core-concepts/apps/connecting-to-apps/app-endpoints/https-endpoints/overview#zero-downtime-deployment).</Tip>

# Zero-Downtime Deployment / Health Checks

gRPC endpoints provide [Zero-Downtime Deployment](/docs/core-concepts/apps/connecting-to-apps/app-endpoints/https-endpoints/overview#zero-downtime-deployment) by leveraging [gRPC Health Checking](https://grpc.io/docs/guides/health-checking/).
Specifically, Aptible will use [health/v1](https://github.com/grpc/grpc-proto/blob/master/grpc/health/v1/health.proto)'s Health.Check call against your service, passing in an empty service name, and will only continue with the deploy if your application responds `SERVING`.

<Warning>When implementing the health service, please ensure you register your service with a blank name, as this is what Aptible looks for.</Warning>

# Idle Timeout

gRPC Endpoints enforce an idle timeout on connections. By default, the inactivity timeout is 60 seconds. You can configure a different timeout per endpoint:

```shell theme={null}
aptible endpoints:grpc:modify --app "$APP_HANDLE" "$ENDPOINT_HOSTNAME" --idle-timeout 1200
```

In Terraform, set `idle_timeout` on the `aptible_endpoint` resource (see [Endpoint Settings](/docs/reference/terraform#endpoint-settings)).

<Warning>**Migrating from environment variables:** `IDLE_TIMEOUT` was previously set as an app configuration variable. Once your endpoints are configured, unset it from your app using `aptible config:unset`.</Warning>

# SSL / TLS Settings

Aptible offers a few ways to configure the protocols used by gRPC endpoints for TLS termination.

# SSL Protocols Override

The SSL Protocols Override setting lets you customize the SSL/TLS protocols allowed on your Endpoint.

* For gRPC Endpoints: you can choose from these combinations:
  * `TLSv1 TLSv1.1 TLSv1.2` (default)
  * `TLSv1.1 TLSv1.2`
  * `TLSv1.2`
  * `TLSv1.3`

# SSL Ciphers Override

This setting lets you customize the SSL ciphers used by your Endpoint.

The format is a string accepted by Nginx for its [ssl\_ciphers directive](http://nginx.org/en/docs/http/ngx_http_ssl_module.html#ssl_ciphers).

Pay very close attention to the required format, as a bad value will prevent the proxies from starting.

# Disable Weak Cipher Suites

Enabling this setting causes your Endpoint to stop accepting traffic over the `SSLv3` protocol or using the `RC4` cipher.

We strongly recommend enabling this on all gRPC Endpoints.

# Examples

## Set Idle Timeout

```shell theme={null}
aptible endpoints:grpc:modify --app "$APP_HANDLE" "$ENDPOINT_HOSTNAME" --idle-timeout 1200
```

## Set SSL Protocols Override

```shell theme={null}
aptible endpoints:grpc:modify --app "$APP_HANDLE" "$ENDPOINT_HOSTNAME" \
        --ssl-protocols-override "TLSv1.1 TLSv1.2"
```

## Disable Weak Cipher Suites

```shell theme={null}
aptible endpoints:grpc:modify --app "$APP_HANDLE" "$ENDPOINT_HOSTNAME" \
        --disable-weak-cipher-suites
```

In Terraform, set `ssl_protocols_override`, `ssl_ciphers_override`, and `disable_weak_cipher_suites` on the `aptible_endpoint` resource (see [Endpoint Settings](/docs/reference/terraform#endpoint-settings)).

<Warning>**Migrating from environment variables:** `SSL_PROTOCOLS_OVERRIDE`, `SSL_CIPHERS_OVERRIDE`, and `DISABLE_WEAK_CIPHER_SUITES` were previously set as app configuration variables. Once your endpoints are configured, unset them from your app using `aptible config:unset`</Warning>


# Endpoint Logs
Source: https://www.aptible.com/docs/core-concepts/apps/connecting-to-apps/app-endpoints/https-endpoints/endpoint-logs



Logs from HTTP(S) Endpoints can be routed to [Log Drains](/docs/core-concepts/observability/logs/log-drains/overview) (select this option when creating the Log Drain). These logs will contain all requests your Endpoint receives, as well as most errors pertaining to the inability of your App to serve a response, if applicable.

<Warning> The Log Drain that receives these logs cannot be pointed at an HTTPS endpoint in the same account. This would cause an infinite loop of logging, eventually crashing your Log Drain. Instead, you can host the target of the Log Drain in another account or use an external service.</Warning>

# Format

Logs are generated by Nginx in the following format, see the [Nginx documentation](http://nginx.org/en/docs/varindex.html) for definitions of specific fields:

```
$remote_addr:$remote_port $ssl_protocol/$ssl_cipher $host $remote_user [$time_local] "$request" $status $body_bytes_sent $request_time "$http_referer" "$http_user_agent" "$http_x_amzn_trace_id" "$http_x_forwarded_for";
```

<Warning> The `$remote_addr` field is not the client's real IP, it is the private network address associated with your Endpoint. To identify the IP Address the end-user connected to your App, you will need to refer to the `X-Forwarded-For` header. See [HTTP Request Headers](/docs/core-concepts/apps/connecting-to-apps/app-endpoints/https-endpoints/http-request-headers) for more information. </Warning>

<Tip> You should log the `X-Amzn-Trace-Id` header in your App, especially if you are proxying this request to another destination. This header will allow you to track requests as they are passed between services.</Tip>

# Metadata

For Log Drains that support embedding metadata in the payload ([HTTPS Log Drains](/docs/core-concepts/observability/logs/log-drains/https-log-drains) and [Self-Hosted Elasticsearch Log Drains](/docs/core-concepts/observability/logs/log-drains/elasticsearch-log-drains)), the following keys are included:

* `endpoint_hostname`: The hostname of the specific Endpoint that serviced this request (eg elb-shared-us-east-1-doit-123456.aptible.in)
* `endpoint_id`: The unique Endpoint ID

# Configuration Options

## Show ELB Health Checks

Endpoint Logs will always emit an error if your App container fails Runtime [Health Checks](/docs/core-concepts/apps/connecting-to-apps/app-endpoints/https-endpoints/health-checks), but by default, they do not log the health check request itself. These are not user requests, are typically very noisy, and are almost never useful since any errors for such requests are logged. See [Common Errors](/docs/core-concepts/apps/connecting-to-apps/app-endpoints/https-endpoints/endpoint-logs#common-errors) for further information about identifying Runtime Health Check errors.

You can enable logging of the health check request via setting configured per endpoint, and can be set in the UI, Terraform Provider, or the CLI. For example, via the CLI:

```shell theme={null}
# Enable
aptible endpoints:https:modify --app "$APP_HANDLE" "$ENDPOINT_HOSTNAME" --show-elb-healthchecks

# Disable
aptible endpoints:https:modify --app "$APP_HANDLE" "$ENDPOINT_HOSTNAME" --no-show-elb-healthchecks
```

Or, in Terraform, set `show_elb_healthchecks` on the `aptible_endpoint` resource (see [Endpoint Settings](/docs/reference/terraform#endpoint-settings)).

<Warning>**Migrating from environment variables:** `SHOW_ELB_HEALTHCHECKS` was previously set as an app configuration variable. Once your endpoints are configured, you should unset it from your app.</Warning>

# Common Errors

When your App does not respond to a request, the Endpoint will return an error response to the client. The client will be served a page that says *This application crashed*, and you will find a log of the corresponding request and error message in your Endpoint Logs. In these errors, "upstream" means your App.

<Note> If you have a [Custom Maintenance Page](/docs/core-concepts/apps/connecting-to-apps/app-endpoints/https-endpoints/maintenance-page#custom-maintenance-page) then you will see your maintenance page instead of *This application crashed*.</Note>

## 502

This response code is generally returned when your App generates a partial or otherwise incomplete response. The specific error logged is usually one of the following messages:

```
(104: Connection reset by peer) while reading response header from upstream
```

```
upstream prematurely closed connection while reading response header from upstream
```

These errors can be attributed to several possible causes:

* Your Container exceeded the [Memory Limit](/docs/core-concepts/scaling/memory-limits) for your Service while serving this request. You can tell if your Container has been restarted after exceeding its Memory Limit by looking for the message `container exceeded its memory allocation` in your [Log Drains](/docs/core-concepts/observability/logs/log-drains/overview).
* Your Container exited unexpectedly for some reason other than a deploy, restart, or exceeding its Memory Limit. This is typically caused by a bug in your App or one of its dependencies. If your Container unexpectedly exits, you will see `container has exited` in your logs.
* A timeout was reached in your App that is shorter than the [Endpoint Timeout](/docs/core-concepts/apps/connecting-to-apps/app-endpoints/overview#timeouts).
* Your App encountered an unhandled exception.

## 504

This response code is generally returned when your App accepts a connection but does not respond at all or does not respond in a timely manner.

The following error message is logged along with the 504 response if the request reaches the idle timeout. See [Endpoint Timeouts](/docs/core-concepts/apps/connecting-to-apps/app-endpoints/overview#timeouts) for more information.

```
(110: Operation timed out) while reading response header from upstream
```

The following error message is logged along with the 504 response if the Endpoint cannot establish a connection to your container at all:

```
(111: Connection refused) while connecting to upstream
```

A connection refused error can be attributed to several possible causes related to the service being unreachable:

* Your Container is in the middle of restarting due to exceeding the [Memory Limit](/docs/core-concepts/scaling/memory-limits) for your Service or because it exited unexpectedly for some reason other than a deploy, restart, or exceeding its Memory Limit.
* The process inside your Container cannot accept any more connections.
* The process inside your container has stopped responding or running entirely.

## Runtime Health Check Errors

Runtime Health Check Errors will be denoted by an error message like the ones documented above and will reference a request path of `/healthcheck`.

See [Runtime Health Checks](/docs/core-concepts/apps/connecting-to-apps/app-endpoints/https-endpoints/health-checks#runtime-health-checks) for more details about how these checks are performed.

# Uncommon Errors

## 499

This is not a response code that is returned to the client, but rather a 499 "response" in the Endpoint log indicates that the client closed the connection before the response was returned. This could be because the user closed their browser or otherwise did not wait for a response.

If you have any other proxy in front of this Endpoint, it may mean that this request reached the other proxy's idle timeout.

## "worker\_connections are not enough"

This error will occur when there are too many concurrent requests for the Endpoint to handle at this time. This can be caused either by an increase in the number of users accessing your system or indirectly by a performance bottleneck causing connections to remain open much longer than usual.

The total concurrent requests that can be opened at once can be increased by [Scaling](/docs/core-concepts/scaling/overview) your App horizontally to add more Containers. However, if the root cause is poor performance of dependencies such as [Databases](/docs/core-concepts/managed-databases/overview), this may only exacerbate the underlying issue.

If scaling your resources appropriately to the load does not resolve this issue, please contact [Aptible Support](/docs/how-to-guides/troubleshooting/aptible-support).


# Header Authentication
Source: https://www.aptible.com/docs/core-concepts/apps/connecting-to-apps/app-endpoints/https-endpoints/header-authentication



[HTTP(S) Endpoints](/docs/core-concepts/apps/connecting-to-apps/app-endpoints/https-endpoints/overview) support header authentication via the `X-Origin-Token` header. This lets you require incoming requests to include a specific token value, providing an additional layer of security beyond [IP Filtering](/docs/core-concepts/apps/connecting-to-apps/app-endpoints/ip-filtering).

<Info>
  Header authentication is available for HTTP(S) Endpoints and can be used alongside [IP Filtering](/docs/core-concepts/apps/connecting-to-apps/app-endpoints/ip-filtering) for additional security.
</Info>

## Use Cases

Header authentication is primarily designed for CDN origin protection. When you place a CDN like AWS CloudFront in front of your Aptible Endpoint, you can configure the CDN to add an `X-Origin-Token` header with a secret value when forwarding requests, and configure your Endpoint to require that same token.

This shared-secret approach helps ensure traffic reaches your app only through the CDN. Direct requests to your Aptible Endpoint URL will receive a `403 Forbidden` response because they won't have the required header. If the token is ever compromised, you should rotate it immediately in both your Endpoint settings and CDN configuration.

Additional use cases include:

* Securing webhooks or API endpoints that should only accept traffic from specific services
* Adding an extra authentication layer for sensitive internal apps
* Protecting staging or preview environments from unauthorized access

## How It Works

When header authentication is enabled, all incoming requests are checked for the `X-Origin-Token` header. Requests with a missing or incorrect header value receive a `403 Forbidden` response. Requests with a matching token proceed normally to your app. The token value is never exposed in responses.

## Enabling Header Authentication

Header authentication is configured via the Aptible Dashboard on a per-Endpoint basis:

* Edit an existing Endpoint or add a new Endpoint
* In the **Header Authentication Value** field, enter your token value
* Click **Save Changes**

## Token Format Requirements

The token value may only contain:

* Letters (a-z, A-Z)
* Numbers (0-9)
* Underscores (`_`)
* Hyphens (`-`)
* Colons (`:`)
* Periods (`.`)

## Removing Header Authentication

To disable header authentication, clear the **Header Authentication Value** field and save your changes.

## Example: CloudFront Integration

To use header authentication with AWS CloudFront:

1. Generate a secure random token value (e.g., using a password generator)
2. Configure the token in your Aptible Endpoint's **Header Authentication Value** setting
3. In CloudFront, add a custom origin header:
   * Header Name: `X-Origin-Token`
   * Header Value: Your token value

Once configured, requests through CloudFront will include the header and reach your app, while direct requests to your Aptible Endpoint will be blocked.


# Health Checks
Source: https://www.aptible.com/docs/core-concepts/apps/connecting-to-apps/app-endpoints/https-endpoints/health-checks



When you add [HTTP(S) Endpoints](/docs/core-concepts/apps/connecting-to-apps/app-endpoints/https-endpoints/overview), Aptible performs health checks on your App [Containers](/docs/core-concepts/architecture/containers/overview) when deploying and throughout their lifecycle.

<Note>The Endpoint has no notion of what hostname the App expects, so it sends health check requests to your application with `containers` as the [host](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Host). This is not a problem for most applications but for those that only allow the use of certain hosts, such as applications built with Django that use `ALLOWED_HOSTS`, this may result in non-200 responses. These applications will need to exempt hostname checking or add `containers` to the list of allowed hosts on `/healthcheck`.</Note>

# Health Check Modes

Health checks on Aptible can operate in two modes:

## Default Health Checks

In this mode (the default), Aptible expects your App Containers to respond to health checks with any valid HTTP response, and does not care about the status code.

## Strict Health Checks

When Strict Health Checks are enabled, Aptible expects your App Containers to respond to health checks with a `200 OK` HTTP response. Any other response will be considered a [failure](/docs/how-to-guides/troubleshooting/common-errors-issues/http-health-check-failed).

Strict Health Checks are useful if you're doing further checking in your App to validate that it's up and running.

To enable Strict Health Checks, configure it directly on each endpoint:

```shell theme={null}
aptible endpoints:https:modify --app "$APP_HANDLE" "$ENDPOINT_HOSTNAME" --strict-health-checks
```

In Terraform, set `strict_health_checks = true` on the `aptible_endpoint` resource (see [Endpoint Settings](/docs/reference/terraform#endpoint-settings)).

<Warning>**Migrating from environment variables:** `STRICT_HEALTH_CHECKS` was previously set as an app configuration variable. Once your endpoints are configured, unset it from your app using `aptible config:unset`</Warning>

<Warning> Redirections are not `200 OK` responses, so be careful with e.g. SSL redirections in your App that could cause your App to respond to the health check with a redirect, such as Rails' `config.force_ssl = true`. Overall, we strongly recommend verifying your logs first to check that you are indeed returning `200 OK` on `/healthcheck` before enabling Strict Health Checks.</Warning>

# Health Check Lifecycle

Aptible performs health checks at two stages:

* [Release Health Checks](/docs/core-concepts/apps/connecting-to-apps/app-endpoints/https-endpoints/health-checks#release-health-checks) when releasing new App [Containers](/docs/core-concepts/architecture/containers/overview).
* [Runtime Health Checks](/docs/core-concepts/apps/connecting-to-apps/app-endpoints/https-endpoints/health-checks#runtime-health-checks) throughout the lifecycle of your App [Containers](/docs/core-concepts/architecture/containers/overview).

## Release Health Checks

When deploying your App, Aptible ensures that new App Containers are receiving traffic before they're registered with load balancers.

When [Strict Health Checks](/docs/core-concepts/apps/connecting-to-apps/app-endpoints/https-endpoints/health-checks#strict-health-checks) are enabled, this request is performed on `/healthcheck`, otherwise, it is simply performed at `/`. In either case, the request is sent to the [Container Port](/docs/core-concepts/apps/connecting-to-apps/app-endpoints/https-endpoints/overview#container-port) for the Endpoint.

### Release Health Check Timeout

By default, Aptible waits for up to 3 minutes for your App to respond. If needed, you can increase that timeout as an endpoint setting.

The value is in seconds. Any value from 1 to 900 (15 minutes) is valid (we recommend avoiding anything below 1 minute).

```shell theme={null}
aptible endpoints:https:modify --app "$APP_HANDLE" "$ENDPOINT_HOSTNAME" \
        --release-healthcheck-timeout 600
```

In Terraform, set `release_healthcheck_timeout` on the `aptible_endpoint` resource (see [Endpoint Settings](/docs/reference/terraform#endpoint-settings)).

<Warning>**Migrating from environment variables:** `RELEASE_HEALTHCHECK_TIMEOUT` was previously set as an app configuration variable. Once your endpoints are configured, unset it from your app using `aptible config:unset`</Warning>

## Runtime Health Checks

When your App is live, Aptible periodically runs a health check to determine if your [Containers](/docs/core-concepts/architecture/containers/overview) are healthy. Traffic will route to a healthy Container, except when:

* No Containers are healthy. Requests will route to **all** Containers, regardless of health status, and will still be visible in your [Endpoint Logs](/docs/core-concepts/apps/connecting-to-apps/app-endpoints/https-endpoints/endpoint-logs).
* Your Service is scaled to zero. Traffic will instead route to [Brickwall](/docs/core-concepts/apps/connecting-to-apps/app-endpoints/https-endpoints/maintenance-page#brickwall), our error page server.

The health check is an HTTP request sent to `/healthcheck`. A healthy Container must respond with `200 OK` HTTP response if [Strict Health Checks](/docs/core-concepts/apps/connecting-to-apps/app-endpoints/https-endpoints/health-checks#strict-health-checks) are enabled, or any status code otherwise. See [Endpoint Logs](/docs/core-concepts/apps/connecting-to-apps/app-endpoints/https-endpoints/endpoint-logs) for information about how Runtime Health Checks error logs can be viewed, and [Health Checks Failed](/docs/how-to-guides/troubleshooting/common-errors-issues/http-health-check-failed) dealing with failures.

<Note> If needed, you can identify requests to `/healthcheck` coming from Aptible: they'll have the `X-Aptible-Health-Check` header set.</Note>

### Mechanics and timing

The following are the intervals and thresholds for runtime health checks:

* **Interval**: every 20 seconds
* **Failed Check**: No response with 15 seconds from a target means a failed health check.
* **Unhealthy threshold**: 3 consecutive failed checks to mark a target unhealthy
* **Healthy threshold**: 2 consecutive successful checks to mark a target healthy

Consider the following impacts and mitigations for when containers are marked unhealthy:

* During the time it takes to confirm your container is unhealthy, requests will still be routed to this container, and you and/or you end users will be impacted if your container does not respond to those requests. When that happens and the app container is not responding, users will see the App's [Maintenance Page](/docs/core-concepts/apps/connecting-to-apps/app-endpoints/https-endpoints/maintenance-page).
* Horizontally scaling a service reduces the impact of a single container becoming unhealthy. For example, if your service runs on 2 containers and one fails, users may experience around one minute of a 50% error rate until traffic fully shifts away from the failing container. Scaling to 5 containers would lower this impact proportionally, resulting in an estimated 20% error rate during the same transition period.
* Using the [least-oustanding-request load balancer strategy](/docs/core-concepts/apps/connecting-to-apps/app-endpoints/https-endpoints/overview#traffic) can be beneficial in mitigating impact while a target/container is transitioning to failed status, since it's likely to have more open/stalled requests, keeping new requests routed to any other containers that are functioning normally.


# HTTP Request Headers
Source: https://www.aptible.com/docs/core-concepts/apps/connecting-to-apps/app-endpoints/https-endpoints/http-request-headers



[HTTP(S) Endpoints](/docs/core-concepts/apps/connecting-to-apps/app-endpoints/https-endpoints/overview) set standard HTTP headers to identify the original IP address of clients making requests to your Apps and the protocol they used:

<Note> Aptible Endpoints only allows headers composed of English letters, digits, hyphens, and underscores. If your App requires headers with other characters such as periods, please [contact Aptible Support](/docs/how-to-guides/troubleshooting/aptible-support).</Note>

# `X-Forwarded-Proto`

This represents the protocol the end-user used to connect to your app. The value can be `http` or `https`.

# `X-Forwarded-For`

This represents the IP Address of the end-user connected to your App.

The `X-Forwarded-For` header is structured as a comma-separated list of IP addresses. It is generated by proxies that handle the request from an end-user to your app (each proxy appends the client IP they see to the header).

Here are a few examples:

## ALB Endpoint, users connect directly to the ALB

In this scenario, the request goes through two hops when it enters Aptible: the ALB, and an Nginx proxy. This means that the ALB will inject the client's IP address in the header, and Nginx will inject the ALB's IP address in the header.

In other words, the header will normally look like this: `$USER_IP,$ALB_IP`.

However, be mindful that end-users may themselves set the `X-Forwarded-For` in their request (typically if they're trying to spoof some IP address validation performed in your app). This means the header might look like this: `$SPOOFED_IP_A,$SPOOFED_IP_B,$SPOOFED_IP_C,$USER_IP,$ALB_IP`.

When processing the `X-Forwarded-For` header, it is important that you always start from the end and work you way back to the IP you're looking for. In this scenario, this means you should look at the second-to-last IP address in the `X-Forwarded-For` header.

## ALB Endpoint, users connect through a CDN

Assuming your CDN only has one hop (review your CDN's documentation for `X-Forwarded-For` if you're unsure), the `X-Forwarded-For` header will look like this: `$USER_IP,$CDN_IP,$ALB_IP`.

Similarly to the example above, keep in mind that the user can inject arbitrary IPs at the head of the list in the `X-Forwarded-For` header. For example, the header could look like this: `$SPOOFED_IP_A,$SPOOFED_IP_B,$USER_IP,$CDN_IP,$ALB_IP`.

So, in this case, you need to look at the third-to-last IP address in the `X-Forwarded-For` header.


# HTTPS Protocols
Source: https://www.aptible.com/docs/core-concepts/apps/connecting-to-apps/app-endpoints/https-endpoints/https-protocols



Aptible allows you to configure the protocols and ciphers used by your [HTTP(S) Endpoints](/docs/core-concepts/apps/connecting-to-apps/app-endpoints/https-endpoints/overview) for HTTPS termination using a single configuration setting. This is configured per endpoint, allowing each endpoint to have independent protocol configuration.

# SSL Protocols Override

The SSL Protocols Override setting lets you customize the SSL/TLS protocols allowed on your Endpoint.

* For ALB Endpoints: you can choose from these 8 combinations:
  * `TLSv1 TLSv1.1 TLSv1.2` (default)
  * `TLSv1 TLSv1.1 TLSv1.2 PFS`
  * `TLSv1.1 TLSv1.2`
  * `TLSv1.1 TLSv1.2 PFS`
  * `TLSv1.2`
  * `TLSv1.2 PFS`
  * `TLSv1.2 PFS TLSv1.3` (see note below comparing ciphers to `TLSv1.2 PFS`)
  * `TLSv1.3`

The ciphers used becomes more restrictive and secure when choosing only newer TLS versions, and choosing options with "PFS".

<Note>
  `PFS` ensures your Endpoint's ciphersuites support perfect forward secrecy on TLSv1.2 or earlier. TLSv1.3 natively includes perfect forward secrecy.
  Note for `TLSv1.2 PFS TLSv1.3`, compared to ciphers for `TLSv1.2 PFS`, this adds `TLSv1.3` ciphers and omits the following:

  * ECDHE-ECDSA-AES128-SHA
  * ECDHE-RSA-AES128-SHA
  * ECDHE-RSA-AES256-SHA
  * ECDHE-ECDSA-AES256-SHA
</Note>

# Examples

## Configuring Allowed SSL Protocols

```shell theme={null}
aptible endpoints:https:modify --app "$APP_HANDLE" "$ENDPOINT_HOSTNAME" \
        --ssl-protocols-override "TLSv1.1 TLSv1.2"
```

In Terraform, set `ssl_protocols_override` on the `aptible_endpoint` resource (see [Endpoint Settings](/docs/reference/terraform#endpoint-settings)).

<Warning>**Migrating from environment variables:** This setting wa previously configured via the `SSL_PROTOCOLS_OVERRIDE`, app configuration variables. Once your endpoints are configured, unset them from your app using `aptible config:unset`.</Warning>


# HTTPS Redirect
Source: https://www.aptible.com/docs/core-concepts/apps/connecting-to-apps/app-endpoints/https-endpoints/https-redirect



<Tip> Your app can detect which protocol is being used by examining a request's `X-Forwarded-Proto` header. See [HTTP Request Headers](/docs/core-concepts/apps/connecting-to-apps/app-endpoints/https-endpoints/http-request-headers) for more information.</Tip>

By default, [HTTP(S) Endpoints](/docs/core-concepts/apps/connecting-to-apps/app-endpoints/https-endpoints/overview) accept traffic over both HTTP and HTTPS.

To disallow HTTP and redirect traffic to HTTPS, enable **Force SSL** on the endpoint. This is an endpoint setting configured per endpoint, so each HTTP(S) endpoint on the same app can have independent behavior.

# Force SSL in detail

Enabling Force SSL on an endpoint causes 2 things to happen:

* Your HTTP(S) Endpoints will redirect all HTTP requests to HTTPS.
* Your HTTP(S) Endpoints will set the `Strict-Transport-Security` header on responses with a max-age of 1 year.

Make sure you understand the implications of setting the `Strict-Transport-Security` header before using this feature.

In particular, by design, clients that connect to your site and receive this header will refuse to reconnect via HTTP for up to a year after they receive the `Strict-Transport-Security` header.

# Enabling Force SSL

Enable or disable Force SSL directly on each endpoint:

```shell theme={null}
# Enable
aptible endpoints:https:modify --app "$APP_HANDLE" "$ENDPOINT_HOSTNAME" --force-ssl

# Disable
aptible endpoints:https:modify --app "$APP_HANDLE" "$ENDPOINT_HOSTNAME" --no-force-ssl
```

In Terraform, set `force_ssl = true` on the `aptible_endpoint` resource. You can also toggle this in the [Aptible Dashboard](https://app.aptible.com) on the endpoint's configuration page.

<Warning>**Migrating from environment variables:** `FORCE_SSL` was previously set as an app configuration variable. Once your endpoints are configured with the desired setting, unset it from your app using `aptible config:unset`</Warning>


# Maintenance Page
Source: https://www.aptible.com/docs/core-concepts/apps/connecting-to-apps/app-endpoints/https-endpoints/maintenance-page



# Custom Maintenance Page

You can configure your Endpoint with a custom maintenance page.

This page will be served by your [HTTP(S) Endpoints](/docs/core-concepts/apps/connecting-to-apps/app-endpoints/https-endpoints/overview) when requests time out, or if your App is down. It will also be served if the Endpoint's underlying [Service](/docs/core-concepts/apps/deploying-apps/services) is scaled to zero.

To configure one, set it as an endpoint setting:

```shell theme={null}
aptible endpoints:https:modify --app "$APP_HANDLE" "$ENDPOINT_HOSTNAME" \
        --maintenance-page-url "http://..."
```

In Terraform, set `maintenance_page_url` on the `aptible_endpoint` resource. You can also update this in the [Aptible Dashboard](https://app.aptible.com) on the endpoint's configuration page.

<Warning>**Migrating from environment variables:** `MAINTENANCE_PAGE_URL` was previously set as an app configuration variable. Once your endpoints are configured, unset it from your app using `aptible config:unset`</Warning>

Aptible will download and cache the maintenance page when deploying your app. If it needs to be served, Aptible will serve the maintenance page directly to clients.

This means:

* Make sure your maintenance page is publicly accessible so that Aptible can download it.
* Don't use relative links in your maintenance page: the page won't be served from its original URL, so relative links will break.

If you don't set up a custom maintenance page, a generic Aptible maintenance page will be served instead.

# Brickwall

If your Service is scaled to zero, Aptible instead will route your traffic to an error page server: *Brickwall*.

Brickwall will serve your `Custom Maintenance Page` if you set one up, and fallback to a generic Aptible error page if you did not.

You usually shouldn't need to, but you can identify responses coming from Brickwall through their `Server` header, which will be set to `brickwall`. Brickwall returns a `502` error code which is not configurable.

If your Service is scaled up, but all app [Containers](/docs/core-concepts/architecture/containers/overview) appear down, Aptible will route your traffic to *all* containers.

# Default Maintenance Page Appearance

<img alt="Default Maintenance Page" />


# HTTP(S) Endpoints
Source: https://www.aptible.com/docs/core-concepts/apps/connecting-to-apps/app-endpoints/https-endpoints/overview



<img alt="Image" />

HTTP(S) Endpoints can be created in the following ways:

* Using the [`aptible endpoints:https:create`](/docs/reference/aptible-cli/cli-commands/cli-endpoints-https-create) command,
* Using the Aptible Dashboard by:
  * Select the App you want to create an endpoint for
  * In the **Endpoints** tab, select **New Endpoint**
  * Customize the endpoint settings as needed:
    * Choose which **Service** you want this endpoint associated with, if applicable
    * Specify a [custom container port](https://www.aptible.com/docs/core-concepts/apps/connecting-to-apps/app-endpoints/https-endpoints/overview#container-port), if needed
    * Choose the **Endpoint Type**
      * [Default domain](/docs/core-concepts/apps/connecting-to-apps/app-endpoints/default-domain)
      * [Custom domain](/docs/core-concepts/apps/connecting-to-apps/app-endpoints/custom-domain) with:
        * [Managed Certificate](/docs/core-concepts/apps/connecting-to-apps/app-endpoints/managed-tls)
        * [Custom Certificate](/docs/core-concepts/apps/connecting-to-apps/app-endpoints/custom-certificate)
    * Choose the [Endpoint Placement](https://www.aptible.com/docs/core-concepts/apps/connecting-to-apps/app-endpoints/overview#endpoint-placement)
    * Enable [IP Filtering](/docs/core-concepts/apps/connecting-to-apps/app-endpoints/ip-filtering), if necessary
    * Enable [Header Authentication](/docs/core-concepts/apps/connecting-to-apps/app-endpoints/https-endpoints/header-authentication) for CDN origin protection, if necessary
    * Choose between the Round Robin (default), Least Outstanding Requests, and Weighted Random load balancing algorithms for request routing.

Like all Endpoints, many HTTP(S) Endpoint settings can be modified using the [`aptible endpoints:https:modify`](/docs/reference/aptible-cli/cli-commands/cli-endpoints-https-modify) command; however, Header Authentication can only be configured via the Aptible Dashboard.

# Traffic

HTTP(S) Endpoints are ideal for web apps. They handle HTTPS termination, and pass it on as HTTP traffic to your app [Containers](/docs/core-concepts/architecture/containers/overview).
HTTP(S) Endpoints can also optionally [redirect HTTP traffic to HTTPS](/docs/core-concepts/apps/connecting-to-apps/app-endpoints/https-endpoints/https-redirect) using the Force SSL endpoint setting.
HTTP(S) Endpoints also allow you to specify how you'd like requests to be routed among containers through the Round Robin, Least Outstanding Requests, and Weighted Random load balancing algorithms.

* Round Robin: The default routing algorithm. Requests are routed evenly to each container sequentially.
* Least Outstanding Requests: Requests are routed to the container with the lowest number of in-process requests.
* Weighted Random: Requests are routed evenly to each container, but in a random order.

<Note>
  HTTP(S) Endpoints can receive client connections from HTTP/1 and HTTP/2, but it is forced down to HTTP/1 through our proxy before it reaches the app.
</Note>

# Container Port

When creating an HTTP Endpoint, you can specify the container port where traffic should be sent. Different [Endpoints](/docs/core-concepts/apps/connecting-to-apps/app-endpoints/overview) can use different ports, even if they're associated with the same [Service](/docs/core-concepts/apps/deploying-apps/services).

If you don't specify a port, Aptible will pick a default port for you. The default port Aptible picks is the lexicographically lowest port exposed by your [Image](/docs/core-concepts/apps/deploying-apps/image/overview). For example, if your Dockerfile contains `EXPOSE 80 443`, then the default port would be `443`.

It's important to make sure your app is listening on the port the Endpoint will route traffic to, or clients won't be able to access your app.

# Zero-Downtime Deployment

HTTP(S) Endpoints provide zero-downtime deployment: whenever you deploy or restart your [App](/docs/core-concepts/apps/overview), Aptible will ensure that new containers are accepting traffic before terminating old containers. For more information on Aptible's deployment process, see [Releases](/docs/core-concepts/apps/deploying-apps/releases/overview).

***

**Keep reading:**

* [Health Checks](/docs/core-concepts/apps/connecting-to-apps/app-endpoints/https-endpoints/health-checks)
* [HTTP Request Headers](/docs/core-concepts/apps/connecting-to-apps/app-endpoints/https-endpoints/http-request-headers)
* [HTTPS Protocols](/docs/core-concepts/apps/connecting-to-apps/app-endpoints/https-endpoints/https-protocols)
* [HTTPS Redirect](/docs/core-concepts/apps/connecting-to-apps/app-endpoints/https-endpoints/https-redirect)
* [Maintenance Page](/docs/core-concepts/apps/connecting-to-apps/app-endpoints/https-endpoints/maintenance-page)
* [Endpoint Logs](/docs/core-concepts/apps/connecting-to-apps/app-endpoints/https-endpoints/endpoint-logs)
* [Shared Endpoints](/docs/core-concepts/apps/connecting-to-apps/app-endpoints/https-endpoints/shared-endpoints)
* [Header Authentication](/docs/core-concepts/apps/connecting-to-apps/app-endpoints/https-endpoints/header-authentication)


# Shared Endpoints
Source: https://www.aptible.com/docs/core-concepts/apps/connecting-to-apps/app-endpoints/https-endpoints/shared-endpoints



HTTP(S) endpoints can be configured to share their underlying load balancer with other endpoints on the stack, reducing the cost of the endpoint. The main limitations of shared endpoints are:

* Clients using the endpoint must support [Server Name Identification (SNI)](https://en.wikipedia.org/wiki/Server_Name_Indication), and send the appropriate `Host` request header. SNI was first implemented in 2004 and has been nearly universally supported by clients since 2014 so only obscure or legacy clients will have issues connecting.
* Wildcard DNS records are not supported. Shared endpoints require a fully qualified domain name. A wildcard certificate can be used in conjunction with providing a domain (see [Configuration](#configuration) for details).
* Some attributes of how Endpoints handle requests are set at the load balancer level, and changing these attributes will migrate your Endpoint to a different load balancer. This comes with some implications for open connections to your endpoint, which are detailed below in the [Configuration](#configuration) section.

## Creating Shared Endpoints

Shared endpoints can be created:

* By checking the "Shared" box when creating an HTTP(S) endpoint using the [Aptible Dashboard](https://app.aptible.com).
* By using the `--shared` flag when creating an HTTP(S) endpoint using the [`aptible endpoints:https:create`](/docs/reference/aptible-cli/cli-commands/cli-endpoints-https-create) CLI command.

Similarly, a dedicated endpoint can be converted to a shared endpoint:

* By checking the "Shared" box when updating a HTTP(S) endpoint using the [Aptible Dashboard](https://app.aptible.com).
* By using the `--shared` flag when updating an HTTP(S) endpoint using the [`aptible endpoints:https:modify`](/docs/reference/aptible-cli/cli-commands/cli-endpoints-https-modify) CLI command.

### Converting to a Dedicated Endpoint

Shared endpoints cannot be converted back to dedicated. To go back to using a dedicated endpoint, create a new dedicated endpoint with the same configuration then delete the shared endpoint when it's no longer needed.

### Configuration

Shared endpoints support the same configuration options as dedicated HTTP(S) endpoints. The only exceptions of note are:

* Shared endpoints using a [Custom Certificate](/docs/core-concepts/apps/connecting-to-apps/app-endpoints/custom-certificate) must specify a fully qualified domain when creating or migrating to a shared endpoint. This is the `--managed-tls-domain` option for CLI commands.
* Shared endpoints do not support managed wildcard domains, a fully qualified domain name must be used with [Managed TLS](/docs/core-concepts/apps/connecting-to-apps/app-endpoints/managed-tls).

The following attributes necessitate changing or replacing the load balancer:

* [IP Filtering](/docs/core-concepts/apps/connecting-to-apps/app-endpoints/ip-filtering)
* [Idle Timeout](/docs/core-concepts/apps/connecting-to-apps/app-endpoints/overview#timeouts)
* [SSL/TLS Protocols](/docs/core-concepts/apps/connecting-to-apps/app-endpoints/https-endpoints/https-protocols)

When making changes to the above attributes, the operation will necessarily take longer in order to avoid interrupting open connections. The following steps are taken, which allow HTTP clients to reconnect smoothly to the new load balancer, before your service is removed from the old load balancer:

1. Wait for DNS changes to propegate
2. Wait for the HTTP client keep-alive timeout to elapse
3. Wait for the TCP idle timeout to elapse
4. Wait up to 15 seconds for in-flight response to to finish sending

If your idle timeout is set to 10 minutes or less, the process will complete without any disruption to a properly functioning client connection. For customers with an idle timeout configured above 10 minutes, we recommend using a dedicated endpoint to avoid interruptions, or reaching out to [Aptible Support](/docs/how-to-guides/troubleshooting/aptible-support) for guidance.

<Warning>Converting an endpoint from dedicated to shared has the same behavior descibed above.</Warning>


# IP Filtering
Source: https://www.aptible.com/docs/core-concepts/apps/connecting-to-apps/app-endpoints/ip-filtering



[Endpoints](/docs/core-concepts/apps/connecting-to-apps/app-endpoints/overview) support IP filtering. This lets you restrict access to Apps hosted on Aptible to a set of whitelisted IP addresses or networks and block other incoming traffic.

The maximum amount of IP sources (aka IPv4 addresses and CIDRs) per Endpoint available for IP filtering is 50. IPv6 is not currently supported.

# Use Cases

While IP filtering is no substitute for strong authentication, it is useful to:

* Further lock down access to sensitive apps and interfaces, such as admin dashboards or third-party apps you're hosting on Aptible for internal use only (For example: Kibana, Sentry).
* Restrict access to your Apps and APIs to a set of trusted customers or data partners.

If you’re hosting development Apps on Aptible, IP filtering can also help you make sure no one outside your company can view your latest and greatest before you're ready to release it to the world.

Note that IP filtering only applies to [Endpoints](/docs/core-concepts/apps/connecting-to-apps/app-endpoints/overview), not to [`aptible ssh`](/docs/reference/aptible-cli/cli-commands/cli-ssh), [`aptible logs`](/docs/reference/aptible-cli/cli-commands/cli-logs), and other backend access functionality provided by the [Aptible CLI](/docs/reference/aptible-cli/cli-commands/overview).

# Enabling IP Filtering

IP filtering is configured via the Aptible Dashboard on a per-Endpoint basis:

* Edit an existing Endpoint or Add a new Endpoint
* Under the **IP Filtering** section, click to enable IP filtering.
* Add the list of IPs in the input area that appears
* Add more sources (IPv4 addresses and CIDRs) by separating them with spaces or newlines
* You must allow traffic from at least one source to enable IP filtering.

When IP Filtering is enabled for an Endpoint, other Apps within the same [Aptible Stack](/docs/core-concepts/architecture/stacks) will no longer be able to connect to the Endpoint. To allow other Apps to connect, just add the Stack's [outbound IP addresses](/docs/core-concepts/apps/connecting-to-apps/outbound-ips) to the list of allowed IPs.

<Tip>
  If Cloudflare proxies traffic to your Endpoint, enable IP filtering and allow Cloudflare's published IP ranges. See [Set Up Cloudflare with Aptible Endpoints](/docs/how-to-guides/app-guides/set-up-cloudflare-with-aptible-endpoints).
</Tip>


# Managed TLS
Source: https://www.aptible.com/docs/core-concepts/apps/connecting-to-apps/app-endpoints/managed-tls



When an [Endpoint](/docs/core-concepts/apps/connecting-to-apps/app-endpoints/overview) requires a Certificate to perform SSL / TLS termination on your behalf, you can opt to let Aptible provision and renew certificates on your behalf. To do so, enable Managed HTTPS when creating your Endpoint. You'll need to provide Aptible with the [Custom Domain](/docs/core-concepts/apps/connecting-to-apps/app-endpoints/custom-domain) name you intend to use so Aptible knows what certificate to provision. Aptible-provisioned certificates are valid for 90 days and are renewed automatically by Aptible.

Alternatively, you can provide your own with a [Custom Certificate](/docs/core-concepts/apps/connecting-to-apps/app-endpoints/custom-certificate).

# Managed HTTPS Validation Records

Managed HTTPS uses [Let's Encrypt](https://letsencrypt.org) under the hood. There are two mechanisms Aptible can use to authorize your domain with Let's Encrypt, and provision certificates on your behalf:

For either of these to work, you'll need to create some CNAMEs in the DNS provider you use for your Custom Domain. The CNAMEs you need to create are listed in the Dashboard.

## http-01

<Info>http-01 verification only works for Endpoints with [External Placement](/docs/core-concepts/apps/connecting-to-apps/app-endpoints/overview#endpoint-placement) that do **not** use [IP Filtering](/docs/core-concepts/apps/connecting-to-apps/app-endpoints/ip-filtering). Wildcard domains are not supported either.</Info>

HTTP verification relies on Let's Encrypt sending an HTTP request to your app and receiving a specific response (presenting that the response is handled by Aptible).

For this to work, you must have a setup a CNAME from your [Custom Domain](/docs/core-concepts/apps/connecting-to-apps/app-endpoints/custom-domain) to the [Endpoint Hostname](/docs/core-concepts/apps/connecting-to-apps/app-endpoints/custom-domain#endpoint-hostname) provided by Aptible.

## dns-01

<Info>Unlike http-01 verification, dns-01 verification works with all Endpoints.</Info>

DNS verification relies on Let's Encrypt checking for the existence of a DNS TXT record with specific contents under your domain.

For this to work, you must have created a CNAME from `_acme-challenge.$DOMAIN` (where `$DOMAIN` is your [Custom Domain](/docs/core-concepts/apps/connecting-to-apps/app-endpoints/custom-domain)) to an Aptible-provided validation name. This name is provided in the Dashboard (it's the `acme` subdomain of the [Endpoint's Hostname](/docs/core-concepts/apps/connecting-to-apps/app-endpoints/custom-domain#endpoint-hostname)). The `acme` subdomain has the TXT record containing the challenge token that Let's Encrypt is looking for.

<Warning>If you have a TXT record defined for `_acme-challenge.$DOMAIN` then Let's Encrypt will use this value instead of the value on the `acme` subdomain and it will not issue a certificate.</Warning>

<Info>If you are using a wildcard domain, then `$DOMAIN` above should be your domain name, but without the leading `*.` portion.</Info>

# Wildcard Domains

Managed TLS supports wildcard domains, which you'll have to verify using [dns-01](/docs/core-concepts/apps/connecting-to-apps/app-endpoints/managed-tls#dns-01).

Aptible automatically creates a SAN certificate for the wildcard and its apex when using a wildcard domain. In other words, if you use `*.$DOMAIN`, then your certificate will be valid for any subdomain of `$DOMAIN`, as well as for `$DOMAIN` itself.

<Warning>A single wildcard domain can only be used by one Endpoint at a time. This is due to the fact that the dns-01 validation record for all Endpoints using the domain will have the same `_acme-challenge` hostname but each requires different data in the record. Therefore, only the Endpoint with the matching record will be able to renew its certificate. If you would like to use the same wildcard certificate with multiple Endpoints you should acquire the certificate from a trusted certificate authority and use it as a [Custom Certificate](/docs/core-concepts/apps/connecting-to-apps/app-endpoints/custom-certificate) on all of the Endpoints.</Warning>

# Rate Limits

Let's Encrypt enforces a number of rate limits on certificate generation. In particular, Let's Encrypt limits the number of certificates you can provision per domain every week. See the [Let's Encrypt Rate Limits](https://letsencrypt.org/docs/rate-limits) documentation for details.

<Warning>When you enable Managed TLS on an Endpoint, Aptible will provision an individual certificate for this Endpoint. If you create an Endpoint, provision a certificate for it via Managed TLS, then deprovision the Endpoint, this certificate will count against your weekly Let's Encrypt rate limit.</Warning>

# Creating CAA Records

If you want to set up a [CAA record](https://en.wikipedia.org/wiki/DNS_Certification_Authority_Authorization) for your domain, please add Let's Encrypt to the list of allowed certificate authorities. Aptible uses Let's Encrypt to provision certificates for your custom domain.


# App Endpoints
Source: https://www.aptible.com/docs/core-concepts/apps/connecting-to-apps/app-endpoints/overview



<img alt="" />

App Endpoints (also referred to as Endpoints) let you expose your Apps on Aptible to clients over the public internet or your [Stack](/docs/core-concepts/architecture/stacks)'s internal network.

An App Endpoint is always associated with a given [Service](/docs/core-concepts/apps/deploying-apps/services): traffic received by the App Endpoint will be load-balanced across all the [Containers](/docs/core-concepts/architecture/containers/overview) for the service, which allows for highly available and horizontally scalable architectures.

<Info>When provisioning a new App Endpoint, make sure the Service is scaled to at least one container. Attempts to create an endpoint on a Service scaled to zero will fail.</Info>

## Types of App Endpoints

The Endpoint type determines the type of traffic the Endpoint accepts (and on which ports it does so) and how that traffic is passed on to your App [Containers](/docs/core-concepts/architecture/containers/overview). Aptible supports four types of App Endpoints:

* [HTTP(S) Endpoints](/docs/core-concepts/apps/connecting-to-apps/app-endpoints/https-endpoints/overview) accept HTTP and HTTPS traffic and forward plain HTTP traffic to your containers. They handle HTTPS termination for you.
* [gRPC Endpoints](/docs/core-concepts/apps/connecting-to-apps/app-endpoints/grpc-endpoints) accept encrypted gRPC traffic and forward plain gRPC traffic to your containers. They handle TLS termination for you.
* [TLS Endpoints](/docs/core-concepts/apps/connecting-to-apps/app-endpoints/tls-endpoints) accept TLS traffic and forward it as TCP to your containers. Here again, TLS termination is handled by the Endpoint.
* [TCP Endpoints](/docs/core-concepts/apps/connecting-to-apps/app-endpoints/tcp-endpoints) accept TCP traffic and forward TCP traffic to your containers.

## Endpoint Placement

App Endpoints can be exposed to the public internet, called **External Placement**, or exposed only to other Apps deployed in the same [Stack, ](/docs/core-concepts/architecture/stacks)called **Internal Placement**.

Regardless of placement, [IP Filtering](/docs/core-concepts/apps/connecting-to-apps/app-endpoints/ip-filtering) allows users to limit which clients are allowed to connect to Endpoints.

<Warning>Do not use internal endpoints as an exclusive security measure. Always authenticate requests to Apps, even Apps that are only exposed over internal Endpoints.</Warning>

<Info>Review [Using Nginx with Aptible Endpoints](/docs/how-to-guides/app-guides/use-nginx-with-aptible-endpoints) for details on using Nginx as a reverse proxy to route traffic to Internal Endpoints.</Info>

## Domain Name

App Endpoints let you bring your own [Custom Domain](/docs/core-concepts/apps/connecting-to-apps/app-endpoints/custom-domain).

If you don't have or don't want to use a Custom Domain, you can use an Aptible-provided [Default Domain](/docs/core-concepts/apps/connecting-to-apps/app-endpoints/default-domain).

## SSL / TLS Certificates

[HTTP(S) Endpoints](/docs/core-concepts/apps/connecting-to-apps/app-endpoints/https-endpoints/overview) and [TLS Endpoints](/docs/core-concepts/apps/connecting-to-apps/app-endpoints/tls-endpoints) perform TLS termination for you, so if you are using either of those, Aptible will need a certificate valid for the hostname you plan to access the Endpoint from.

There are two cases here:

* If you are using a [Default Domain](/docs/core-concepts/apps/connecting-to-apps/app-endpoints/default-domain), Aptible controls the hostname and will provide an SSL/TLS Certificate as well.
* However, if you are using a [Custom Domain](/docs/core-concepts/apps/connecting-to-apps/app-endpoints/custom-domain), you will need to provide Aptible with a [Custom Certificate](/docs/core-concepts/apps/connecting-to-apps/app-endpoints/custom-certificate), or enable [Managed TLS](/docs/core-concepts/apps/connecting-to-apps/app-endpoints/managed-tls) and let Aptible provision the certificate for you.

## Timeouts

App Endpoints enforce idle timeouts on traffic, so clients will be disconnected after a configurable inactivity timeout.

By default, the inactivity timeout is 60 seconds. You can configure a different timeout directly on each endpoint, allowing independent timeouts per endpoint on the same app. The timeout can be set to any value from 30 to 2400 seconds.

For example, to set a 20-minute idle timeout on an HTTPS endpoint:

```shell theme={null}
aptible endpoints:https:modify --app "$APP_HANDLE" "$ENDPOINT_HOSTNAME" --idle-timeout 1200
```

For other endpoint types, use the corresponding modify command (`endpoints:grpc:modify`, `endpoints:tls:modify`, `endpoints:tcp:modify`). In Terraform, set `idle_timeout` on the `aptible_endpoint` resource.

<Warning>**Migrating from environment variables:** `IDLE_TIMEOUT` was previously set as an app configuration variable. Once your endpoints are configured with the desired timeout, unset it from your app using aptible config:unset\`</Warning>

This setting also determines the HTTP keep-alive timeout, ensuring that your clients attempt to reconnect to your services periodically. This ensures your clients benefit from the platform's availability and scalability mechanisms, while still being able to send multiple requests over a persistent HTTP/2 or HTTP/1.1 connection. If a client attempts to use a connection for longer than your configured IDLE\_TIMEOUT, the load balancer will append the `Connection: close` header to the response, and close the connection after the response is complete.

## Inbound IP Addresses

App Endpoints use dynamic IP addresses, so no static IP addresses are available.

<Note>Each Endpoint uses an AWS Elastic Load Balancer, which uses dynamic IP addresses to seamlessly scale based on request growth and provides seamless maintenance (of the ALB itself by AWS). As such, AWS may change the set of IP addresses at any time.</Note>


# TCP Endpoints
Source: https://www.aptible.com/docs/core-concepts/apps/connecting-to-apps/app-endpoints/tcp-endpoints



<img alt="Image" />

TCP Endpoints can be created using the [`aptible endpoints:tcp:create`](/docs/reference/aptible-cli/cli-commands/cli-endpoints-tcp-create) command.

## Traffic

TCP Endpoints pass the TCP traffic they receive directly to your app.

## Container Ports

When creating a TCP Endpoint, you can specify the container ports the Endpoint should listen on. If you don't specify a port, Aptible will use all the ports exposed by your [Image](/docs/core-concepts/apps/deploying-apps/image/overview).

The TCP Endpoint will listen for traffic on the ports you expose and transfer that traffic to your app [Containers](/docs/core-concepts/architecture/containers/overview) on the same port.

For example, if you expose ports `123` and `456`, the Endpoint will listen on those two ports. Traffic received by the Endpoint on port `123` will be sent to your app containers on port `123`, and traffic received by the Endpoint on port `456` will be sent to your app containers on port `456`.

You may expose at most 10 ports. Note that this means that if your image exposes more than 10 ports, you will need to specify which ones should be exposed to provision TCP Endpoints.

## FAQ

<AccordionGroup>
  <Accordion title="Do TCP Endpoints support SSL?">
    If you need a higher level of control over TLS negotiation, we would suggest using a TCP Endpoint so that you can perform TLS termination in your application containers with the level of control that you need.
  </Accordion>

  <Accordion title="Are TCP Endpoints safe without SSL?">
    Some resources (postgresql for example, in unison with [pgbouncer](https://www.pgbouncer.org/)) have TLS built into their protocols, which means utilizing a TCP endpoint would be necessary, appropriate, and safe. Reviewing and aligning with protocols associated with your application requirements can provide insight on whether TCP endpoints are applicable.
  </Accordion>
</AccordionGroup>

<Warning>Unlike [HTTP(S) Endpoints](/docs/core-concepts/apps/connecting-to-apps/app-endpoints/https-endpoints/overview), TCP Endpoints currently do not provide [Zero-Downtime Deployment](/docs/core-concepts/apps/connecting-to-apps/app-endpoints/https-endpoints/overview#zero-downtime-deployment). If you require Zero-Downtime Deployment for a TCP app, you'd need to architect it yourself, e.g. at the DNS level.</Warning>


# TLS Endpoints
Source: https://www.aptible.com/docs/core-concepts/apps/connecting-to-apps/app-endpoints/tls-endpoints



<img alt="Image" />

TLS Endpoints can be created using the [`aptible endpoints:tls:create`](/docs/reference/aptible-cli/cli-commands/cli-endpoints-tls-create) command.

## Traffic

TLS Endpoints terminate TLS traffic and transfer it as plain TCP to your app.

## Container Ports

TLS Endpoints are configured similarly to [TCP Endpoints](/docs/core-concepts/apps/connecting-to-apps/app-endpoints/tcp-endpoints).

The Endpoint will listen for TLS traffic on exposed ports and transfer it as TCP traffic to your app over the same port. For example, if your [Image](/docs/core-concepts/apps/deploying-apps/image/overview) exposes port `123`, the Endpoint will listen for TLS traffic on port `123`, and forward it as TCP traffic to your app [Containers](/docs/core-concepts/architecture/containers/overview) on port `123`.

<Warning>Unlike [HTTP(S) Endpoints](/docs/core-concepts/apps/connecting-to-apps/app-endpoints/https-endpoints/overview), TLS Endpoints currently do not provide [Zero-Downtime Deployment](/docs/core-concepts/apps/connecting-to-apps/app-endpoints/https-endpoints/overview#zero-downtime-deployment). If you require Zero-Downtime Deployments for a TLS app, you'd need to architect it yourself, e.g. at the DNS level.</Warning>

# Idle Timeout

TLS Endpoints enforce an idle timeout on connections. By default, the inactivity timeout is 60 seconds. You can configure a different timeout per endpoint:

```shell theme={null}
aptible endpoints:tls:modify --app "$APP_HANDLE" "$ENDPOINT_HOSTNAME" --idle-timeout 1200
```

In Terraform, set `idle_timeout` on the `aptible_endpoint` resource (see [Endpoint Settings](/docs/reference/terraform#endpoint-settings)).

<Warning>**Migrating from environment variables:** `IDLE_TIMEOUT` was previously set as an app configuration variable. Once your endpoints are configured, unset it from your app using `aptible config:unset`</Warning>

# SSL / TLS Settings

Aptible offers a few ways to configure the protocols used by TLS endpoints for TLS termination.

## SSL Protocols Override

The SSL Protocols Override setting lets you customize the SSL/TLS protocols allowed on your Endpoint.

* For TLS Endpoints: you can choose from these combinations:
  * `TLSv1 TLSv1.1 TLSv1.2` (default)
  * `TLSv1.1 TLSv1.2`
  * `TLSv1.2`
  * `TLSv1.3`

## SSL Ciphers Override

This setting lets you customize the SSL ciphers used by your Endpoint.

The format is a string accepted by Nginx for its [ssl\_ciphers directive](http://nginx.org/en/docs/http/ngx_http_ssl_module.html#ssl_ciphers).

Pay very close attention to the required format, as a bad value will prevent the proxies from starting.

## Disable Weak Cipher Suites

Enabling this setting causes your Endpoint to stop accepting traffic over the `SSLv3` protocol or using the `RC4` cipher.

We strongly recommend enabling this on all TLS Endpoints.

## Examples

## Set Idle Timeout

```shell theme={null}
aptible endpoints:tls:modify --app "$APP_HANDLE" "$ENDPOINT_HOSTNAME" --idle-timeout 1200
```

## Set SSL Protocols Override

```shell theme={null}
aptible endpoints:tls:modify --app "$APP_HANDLE" "$ENDPOINT_HOSTNAME" \
        --ssl-protocols-override "TLSv1.2 TLSv1.3"
```

## Disable Weak Cipher Suites

```shell theme={null}
aptible endpoints:tls:modify --app "$APP_HANDLE" "$ENDPOINT_HOSTNAME" \
        --disable-weak-cipher-suites
```

In Terraform, set `ssl_protocols_override`, `ssl_ciphers_override`, and `disable_weak_cipher_suites` on the `aptible_endpoint` resource (see [Endpoint Settings](/docs/reference/terraform#endpoint-settings)).

<Warning>**Migrating from environment variables:** `SSL_PROTOCOLS_OVERRIDE`, `SSL_CIPHERS_OVERRIDE`, and `DISABLE_WEAK_CIPHER_SUITES` were previously set as app configuration variables. Once your endpoints are configured, unset them from your app using `aptible config:unset`</Warning>


# Outbound IP Addresses
Source: https://www.aptible.com/docs/core-concepts/apps/connecting-to-apps/outbound-ips

Learn about using outbound IP addresses to create an allowlist

# Overview

You can share an app's outbound IP address pool with partners or vendors that use an allowlist.

<Note> [Stacks](/docs/core-concepts/architecture/stacks) have a single NAT gateway, and all requests originating from an app use the outbound IP addresses associated with that NAT gateway's IP address.</Note>

These IP addresses are *different* from the IP addresses associated with an app's [Endpoints](/docs/core-concepts/apps/connecting-to-apps/app-endpoints/overview), which are used for *inbound* requests.

The outbound IP addresses for an app *may* change for the following reasons:

1. Aptible migrates the [Environment](/docs/core-concepts/architecture/environments) the app is deployed on to a new [stack](/docs/core-concepts/architecture/stacks)
2. Failure of the underlying NAT instance
3. Failover to minimize downtime during maintenance

In either case, Aptible selects the new IP address from a pool of pre-defined IP addresses associated with the NAT gateway. This set pool will not change without notification from Aptible.

<Warning> For this reason, when sharing IP addresses with vendors or partners for whitelisting, ensure all of the provided outbound IP addresses are whitelisted. </Warning>

# Email Notifications for IP Changes

When Aptible adds new outbound IP addresses to your stack's NAT gateway pool, email notifications are sent to:

* Your organization's Ops Alert contact
* All account owners

This ensures timely notification of this important change to all key organization members.

# Determining Outbound IP Address Pool

Your outbound IP address pool can be identified by navigating to the [Stack](/docs/core-concepts/architecture/stacks) with the Aptible Dashboard.


# Connecting to Apps
Source: https://www.aptible.com/docs/core-concepts/apps/connecting-to-apps/overview

Learn how to connect to your Aptible Apps

# App Endpoints (Load Balancers)

Expose your apps to the internet via Endpoints. All traffic received by the Endpoint will be load-balanced across all the Containers for the service. IP Filtering locks down which clients are allowed to connect to your Endpoint.

<Card title="Learn more aobut App Endpoints (Load Balancers)" icon="book" href="https://www.aptible.com/docs/endpoints" />

# Ephemeral SSH Sessions

Create an ephemeral SSH Session configured identically to your App Containers. These Ephemeral SSH Sessions are great for debugging, one-off scripts, and running ad-hoc jobs.

<Card title="Learn more about Ephemeral SSH Sessions" icon="book" href="https://www.aptible.com/docs/ssh-sessions" />

# Outbound IP Addresses

Share an App's outbound IP address with partners or vendors that use an allowlist

<Card title="Learn more about Outbound IP Addresses" icon="book" href="https://www.aptible.com/docs/outbound-ips" />


# Ephemeral SSH Sessions
Source: https://www.aptible.com/docs/core-concepts/apps/connecting-to-apps/ssh-sessions

Learn about using Ephemeral SSH sessions on Aptible

# Overview

Aptible offers Ephemeral SSH Sessions for accessing containers that are configured identically to App containers, making them ideal for managing consoles and running ad-hoc jobs.

Unlike regular containers, ephemeral containers won't be restarted when they crash. If your connection to Aptible drops, the remote Container will be terminated.

## Creating Ephemeral SSH Sessions

Ephemeral SSH Sessions can be created using the [`aptible ssh`](/docs/reference/aptible-cli/cli-commands/cli-ssh) command.

<Note> Ephemeral containers are not the same size as your App Container. By default, ephemeral containers are scaled to 1024 MB. </Note>

# Terminating Ephemeral SSH Sessions

### Manually Terminating

You can terminate your SSH sessions by closing the terminal session you spawned it in or exiting the container.

<Tip> It may take a bit of time for our API to acknowledge that the SSH session is shut down. If you're running into Plan Limits trying to create another one, wait a few minutes and try again.</Tip>

### Expiration

SSH sessions will automatically terminate upon expiration. By default, SSH sessions will expire after seven days. Contact [Aptible Support](/docs/how-to-guides/troubleshooting/aptible-support) to reduce the default SSH session duration for Dedicated [Stacks](/docs/core-concepts/architecture/stacks). Please note that this setting takes effect regardless of whether the session is active or idle.

<Note> When you create a SSH session using [`aptible ssh`](/docs/reference/aptible-cli/cli-commands/cli-ssh), you're logging in to an **ephemeral** container. You are **not** logging to one of your running app containers. This means that running commands like `ps` won't reflect what's actually running in your App containers, and that files that exist in your App containers will not be present in the ephemeral session. </Note>

# Logging

<Warning> **If you process PHI or  sensitive information in your app or database:** it's very likely that PHI will at some point leak in your SSH session logs. To ensure compliance, make sure you have the appropriate agreements in place with your logging provider before sending your SSH logs there. For PHI, you'll need a BAA. </Warning>

Logs from Ephemeral SSH Sessions can be routed to [Log Drains](/docs/core-concepts/observability/logs/log-drains/overview).

Note that for interactive sessions, Aptible allocates a TTY for your container, so your Log Drain will receive exactly what the end user is seeing. This has two benefits:

* You see the user's input as well.
* If you’re prompting the user for a password using a safe password prompt that does not write back anything, nothing will be sent to the Log Drain either. That prevents you from leaking your passwords to your logging provider.

## Metadata

For Log Drains that support embedding metadata in the payload ([HTTPS Log Drains](/docs/core-concepts/observability/logs/log-drains/https-log-drains) and [Self-Hosted Elasticsearch Log Drains](/docs/core-concepts/observability/logs/log-drains/elasticsearch-log-drains)), the following keys are included:

* `operation_id`: The ID of the Operation that resulted in the creation of this Ephemeral Session.
* `operation_user_name`: The name of the user that created the Operation.
* `operation_user_email`: The email of the user that created the Operation.
* `APTIBLE_USER_DOCUMENT`: An expired JWT object with user information.

For Log Drains that don't support embedding metadata (i.e., [Syslog Log Drains](/docs/core-concepts/observability/logs/log-drains/syslog-log-drains)), the ID of the Operation that created the session is included in the logs.


# Configuration
Source: https://www.aptible.com/docs/core-concepts/apps/deploying-apps/configuration

Learn about how configuration variables provide persistent environment variables for your app's containers, simplifying settings management

# Overview

Configuration variables contain a collection of keys and values, which will be made available to your app's containers as environment variables. Configurable variables persist once set, eliminating the need to repeatedly set the variables upon deploys. These variables will remain available in your app containers until modified or unset.

### Platform-specific Configuration Variables

While generally deprecated, some platform behavior is controlled by specific variables:

* `APTIBLE_DO_NOT_WIPE` (See [Disabling filesystem wipes](/docs/core-concepts/architecture/containers/container-recovery#disabling-filesystem-wipes))
* `APTIBLE_ACK_COMPANION_REPO_DEPRECATION` (See [Companion Git Repository](/docs/core-concepts/apps/deploying-apps/image/deploying-with-docker-image/companion-git-repository))

<Warning>The following variables are **deprecated**. They have been replaced by dedicated endpoint settings or app deployment settings and should be unset from your app configuration once you have migrated </Warning>

* **Deprecated** `FORCE_SSL` — now an endpoint setting. (See [HTTPS Redirect](/docs/core-concepts/apps/connecting-to-apps/app-endpoints/https-endpoints/https-redirect))
* **Deprecated** `STRICT_HEALTH_CHECKS` — now an endpoint setting. (See [Strict Health Checks](/docs/core-concepts/apps/connecting-to-apps/app-endpoints/https-endpoints/health-checks#strict-health-checks))
* **Deprecated** `IDLE_TIMEOUT` — now an endpoint setting. (See [Endpoint Timeouts](/docs/core-concepts/apps/connecting-to-apps/app-endpoints/overview#timeouts))
* **Deprecated** `SSL_PROTOCOLS_OVERRIDE` — now an endpoint setting. (See [HTTPS Protocols](/docs/core-concepts/apps/connecting-to-apps/app-endpoints/https-endpoints/https-protocols))
* **Deprecated** `SSL_CIPHERS_OVERRIDE` — now an endpoint setting. (See [HTTPS Protocols](/docs/core-concepts/apps/connecting-to-apps/app-endpoints/https-endpoints/https-protocols))
* **Deprecated** `DISABLE_WEAK_CIPHER_SUITES` — now an endpoint setting. (See [HTTPS Protocols](/docs/core-concepts/apps/connecting-to-apps/app-endpoints/https-endpoints/https-protocols))
* **Deprecated** `SHOW_ELB_HEALTHCHECKS` — now an endpoint setting. (See [Endpoint Logs](/docs/core-concepts/apps/connecting-to-apps/app-endpoints/https-endpoints/endpoint-logs#configuration-options))
* **Deprecated** `RELEASE_HEALTHCHECK_TIMEOUT` — now an endpoint setting. (See [Release Health Checks](/docs/core-concepts/apps/connecting-to-apps/app-endpoints/https-endpoints/health-checks#release-health-checks))
* **Deprecated** `MAINTENANCE_PAGE_URL` — now an endpoint setting. (See [Maintenance Page](/docs/core-concepts/apps/connecting-to-apps/app-endpoints/https-endpoints/maintenance-page))
* **Deprecated** `APTIBLE_PRIVATE_REGISTRY_USERNAME` — use the `--private-registry-username` flag with `aptible deploy` or the `private_registry_username` Terraform attribute instead. (See [Private Registry Authentication](/docs/core-concepts/apps/deploying-apps/image/deploying-with-docker-image/overview#private-registry-authentication))
* **Deprecated** `APTIBLE_PRIVATE_REGISTRY_PASSWORD` — use the `--private-registry-password` flag with `aptible deploy` or the `private_registry_password` Terraform attribute instead. (See [Private Registry Authentication](/docs/core-concepts/apps/deploying-apps/image/deploying-with-docker-image/overview#private-registry-authentication))

# FAQ

<AccordionGroup>
  <Accordion title="How do I set or modify configuration variables?">
    See related guide:

    <Card title="How to set or modify configuration variables" icon="book-open-reader" href="https://www.aptible.com/docs/set-configuration-variables" />
  </Accordion>

  <Accordion title="How do I synchronize configuration and code change?">
    See related guide:

    <Card title="How to synchronize configuration and code changes" icon="book-open-reader" href="https://www.aptible.com/docs/synchronized-deploys" />
  </Accordion>
</AccordionGroup>


# Deploying with Docker Image
Source: https://www.aptible.com/docs/core-concepts/apps/deploying-apps/image/deploying-with-docker-image/overview

Learn about the deployment method for the most control: deploying via Docker Image

<img alt="" />

# Overview

If you need absolute control over your Docker image's build, Aptible lets you deploy directly from a Docker image. Additionally, [Aptible's Terraform Provider](/docs/reference/terraform) currently only supports deploying via Docker image - so this is a benefit to using this deployment method.

The workflow for deploying via Docker image is as follows:

1. You build your Docker image locally or in a CI platform
2. You push the image to a Docker registry
3. You use the [`aptible deploy`](/docs/reference/aptible-cli/cli-commands/cli-deploy) command to initiate a deployment on Aptible from the image stored in your registry.

# Private Registry Authentication

You may need to provide Aptible with private registry credentials to pull images on your behalf. Pass them using the `--private-registry-username` and `--private-registry-password` flags on `aptible deploy`, or set `private_registry_username` and `private_registry_password` on the `aptible_app` resource in Terraform.

<Note> If you provide registry credentials, Aptible will use them regardless of whether the image you are attempting to pull is public or private. </Note>

## Long term credentials

Most Docker image registries provide long-term credentials, which you only need to provide once to Aptible.

When deploying via Docker image, you only need to provide the registry credentials the first time you deploy.

```javascript theme={null}
aptible deploy \
--app "$APP_HANDLE" \
--docker-image "$DOCKER_IMAGE" \
--private-registry-username "$USERNAME" \
--private-registry-password "$PASSWORD"
```

## Short term credentials

Some registries, like AWS Elastic Container Registry (ECR), only provide short-term credentials. In these cases, you will likely need to update your registry credentials every time you deploy.

When deploying via Docker image, you need to provide updated credentials whenever you deploy, as if it were the first time you deployed:

```javascript theme={null}
aptible deploy \
--app "$APP_HANDLE" \
--docker-image "$DOCKER_IMAGE" \
--private-registry-username "$USERNAME" \
--private-registry-password "$PASSWORD"
```

# FAQ

<AccordionGroup>
  <Accordion title="How do I deploy from Docker Image?">
    See related guide:

    <Card title="How to deploy via Docker Image" icon="book-open-reader" href="https://www.aptible.com/docs/direct-docker-image-deploy-example" />
  </Accordion>

  <Accordion title="How do I switch from deploying with Git to deploying from Docker Image?">
    See related guide:

    <Card title="How to migrate from deploying via Docker Image to deploying via Git" icon="book-open-reader" href="https://www.aptible.com/docs/migrating-from-dockerfile-deploy" />
  </Accordion>

  <Accordion title="How do I synchronize configuration and code change?">
    See related guide:

    <Card title="How to synchronize configuration and code changes" icon="book-open-reader" href="https://www.aptible.com/docs/synchronized-deploys" />
  </Accordion>
</AccordionGroup>


# Procfiles and  `.aptible.yml`
Source: https://www.aptible.com/docs/core-concepts/apps/deploying-apps/image/deploying-with-docker-image/procfile-aptible-yml-direct-docker-deploy



To provide a [Procfile](/docs/how-to-guides/app-guides/define-services) or a [`.aptible.yml`](/docs/core-concepts/apps/deploying-apps/releases/aptible-yml) when [deploying via Docker image](/docs/how-to-guides/app-guides/migrate-dockerfile-to-direct-image-deploy), you need to include these files in your Docker image at a pre-defined location:

* The `Procfile` must be located at `/.aptible/Procfile`.
* The `.aptible.yml` must be located at `/.aptible/.aptible.yml`.

Both of these files are optional: when you deploy directly from a Docker image, Aptible uses your image's `CMD` to know which service command to run.

# Creating a suitable Docker Image

Here is how you can create those files in your Dockerfile, assuming you have files named `Procfile` and `.aptible.yml` at the root of your Docker build context:

```dockerfile theme={null}
RUN mkdir /.aptible/
ADD Procfile /.aptible/Procfile
ADD .aptible.yml /.aptible/.aptible.yml
```

Note that if you are using `docker build .` to build your image, then the build context is the current directory.


# Docker Build
Source: https://www.aptible.com/docs/core-concepts/apps/deploying-apps/image/deploying-with-git/build



# Build context

When Aptible builds your Docker image using [deploying via Git](/docs/how-to-guides/app-guides/deploy-from-git), the build context contains the git repository you pushed and a [`.aptible.env`](/docs/how-to-guides/app-guides/access-config-vars-during-docker-build#aptible-env) file injected by Aptible at the root of your repository.

Here are a few caveats you should be mindful of:

* **Git clone is a shallow clone**
  * When Aptible ships your git repository to a build instance, it uses a git shallow clone.
  * This has no impact on the code being cloned, but you should be mindful that using e.g. `git log` within your container will yield a single commit: the one you deployed from.
* **File timestamps are all set to January 1st, 2000**
  * Git does not preserve timestamps on files. This means that when Aptible clones a git repository, the timestamps on your files represent when the files were cloned, as opposed to when you last modified them.
  * However, Docker caching relies on timestamps (i.e., a different timestamp will break the Docker build cache), so timestamps that reflect the clone time would break Docker caching.
  * To optimize your build times, Aptible sets all the timestamps on all files in your repository to an arbitrary timestamp: January 1st, 2000, at 00:00 UTC.
* **`.dockerignore` is not used**
  * The `.dockerignore` file is read by the Docker CLI client, not by the Docker server.
  * However, Aptible does not use the Docker CLI client and does not currently use the `.dockerignore` file.

# Multi-stage builds

Although Aptible supports [multi-stage builds](https://docs.docker.com/build/building/multi-stage/), there are a few points to keep in mind:

* You cannot specify a target stage to be built within Aptible. This means the final stage is always used as the target.
* Aptible always builds all stages regardless of dependencies or lack thereof in the final stage.


# Deploying with Git
Source: https://www.aptible.com/docs/core-concepts/apps/deploying-apps/image/deploying-with-git/overview

Learn about the easiest deployment method to get started: deploying via Git Push

<img alt="" />

# Overview

Deploying via [Git](https://git-scm.com/) is the easiest deployment method to get up and running on Aptible - if you're migrating over from another Platform-as-a-Service or your team isn't using Docker yet.

The deployment process is as follows:

1. You add a [Dockerfile](/docs/how-to-guides/app-guides/deploy-from-git#dockerfile) at the root of your code repository and commit it.
2. You use `git push` to push your code repository to a [Git Remote](/docs/how-to-guides/app-guides/deploy-from-git#git-remote) provided by Aptible.
3. Aptible builds a new [image](/docs/core-concepts/apps/deploying-apps/image/overview) from your Dockerfile and deploys it to new [app](/docs/core-concepts/apps/overview) containers

# Get Started

If you are just getting started [deploy a starter template](/docs/getting-started/deploy-starter-template/overview) or [review guides for deploying with Git](/docs/how-to-guides/app-guides/deploy-from-git#featured-guide).

# Dockerfile

The Dockerfile is a series of instructions that indicate how Docker should build an image for your app when you [deploy via Git](/docs/how-to-guides/app-guides/deploy-from-git).

To build your Dockerfile on Aptible, the file must be named Dockerfile, and located at the root of your repository.

If it takes Aptible longer than 30 minutes to build your image from the Dockerfile, the deploy [Operation](/docs/core-concepts/architecture/operations) will time out. If your image takes long to build, consider [deploying via Docker image](/docs/how-to-guides/app-guides/migrate-dockerfile-to-direct-image-deploy).

<Tip>New to Docker? Check out our [guide for Getting Started with Docker.](/docs/how-to-guides/app-guides/getting-started-with-docker)</Tip>

# Git Remote

A Git Remote is a reference to a repository stored on a remote server. When you provision an Aptible app, the platform creates a unique Git Remote. For example:

```javascript theme={null}
git @beta.aptible.com: $ENVIRONMENT_HANDLE / $APP_HANDLE.git
```

When deploying via Git, you push your code repository to the unique Git Remote for your app. To do this, you must:

* Register an [SSH Public Key](/docs/core-concepts/security-compliance/authentication/ssh-keys) with Aptible
* Push your code to the master or main branch of the Aptible Git Remote

<Warning> If [SSO is required for accessing](/docs/core-concepts/security-compliance/authentication/sso#require-sso-for-access) your Aptible organization, attempts to use the Git Remote will return an App not found or not accessible error. Users will need to be added to the [SSO Bypass Allowlist](/docs/core-concepts/security-compliance/authentication/sso#exempt-users-from-sso-requirement) to access your organization's resources via Git. </Warning>

## Branches and refs

There are three branches that take action on push.

* `master` and `main` attempt to deploy the incoming code before accepting the changes.
* `aptible-scan` checks that the repo is deployable, usually by verifying the dockerfile can be built.

If you push to a different branch, you can manually deploy the branch using the `aptible deploy --git-commitish $BRANCH_NAME` [CLI command](/docs/reference/aptible-cli/cli-commands/cli-deploy). This can also be used to [synchronize code and configuration changes](/docs/how-to-guides/app-guides/synchronize-config-code-changes).

When pushing multiple refs, each is processed individually. This means, for example you could check the deployability of your repo and push to an alternate branch using `git push $APTIBLE_REMOTE $BRANCH_NAME:aptible-scan $BRANCH_NAME`.

### Aptible's Git Server's SSH Key Fingerprints

For an additional security check, public key fingerprints can be used to validate the connection to Aptible's Git server. These are Aptible's public key fingerprints for the Git server (beta.aptible.com):

* SHA256:tA38HY1KedlJ2GRnr5iDB8bgJe9OoFOHK+Le1vJC9b0 (RSA)
* SHA256:FsLUs5U/cZ0nGgvy/OorvGSaLzvLRSAo4+xk6+jNg8k (ECDSA)

# Private Registry Authentication

You may need to provide Aptible with private registry credentials to pull images on your behalf. To do this, use the following [configuration](/docs/core-concepts/apps/deploying-apps/configuration) variables.

* `APTIBLE_PRIVATE_REGISTRY_USERNAME`
* `APTIBLE_PRIVATE_REGISTRY_PASSWORD`

<Note> Aptible will use configuration varibles when the image is attempting to be pulled is public or private. Configuration variables can be unset by setting them to an empty string ("").</Note>

## Long term credentials

Most Docker image registries provide long-term credentials, which you only need to provide once to Aptible.

It's recommended to set the credentials before updating your `FROM` declaration to depend on a private image and push your Dockerfile to Aptible. Credentials can be set in the following ways:

* From the Aptible Dashboard by
  * Navigating to the App
  * Selecting the \*\*Configuration \*\*tab
* Using the [`aptible config:set`](/docs/reference/aptible-cli/cli-commands/cli-config-set) CLI command:

```javascript theme={null}
aptible config: set \
--app "$APP_HANDLE" \
"APTIBLE_PRIVATE_REGISTRY_USERNAME=$USERNAME"
"APTIBLE_PRIVATE_REGISTRY_PASSWORD=$PASSWORD"
```

## Short term credentials

Some registries, like AWS Elastic Container Registry (ECR), only provide short-term credentials. In these cases, you will likely need to update your registry credentials every time you deploy.

Since Docker credentials are provided as [configuration](/docs/core-concepts/apps/deploying-apps/configuration) variables, you'll need to use the CLI in addition to `git push` to deploy. There are two solutions to this problem.

1. **Recommended**:
   [Synchronize configuration and code changes](/docs/how-to-guides/app-guides/synchronize-config-code-changes). This approach is the fastest.
2. Update the variables using [`aptible config:set`](/docs/reference/aptible-cli/cli-commands/cli-config-set), deploy using `git push aptible master`, and restart your app to apply to apply the configuration change before the deploy can start. This approach is slower.

# FAQ

<AccordionGroup>
  <Accordion title="How do I deploy with Git Push?">
    See related guide:

    <Card title="How to deploy from Git" icon="book-open-reader" href="https://www.aptible.com/docs/dockerfile-deploy-example" />
  </Accordion>

  <Accordion title="How do I switch from deploying via Docker Image to deploying via Git?">
    See related guide:

    <Card title="How to migrate from deploying via Docker Image to deploying via Git" icon="book-open-reader" href="https://www.aptible.com/docs/migrating-from-direct-docker-image-deploy" />
  </Accordion>

  <Accordion title="How do I access configuration variables during Docker build?">
    See related guide:

    <Card title="How to access configuration variables during Docker build" icon="book-open-reader" href="https://www.aptible.com/docs/docker-build-configuration" />
  </Accordion>

  <Accordion title="How do I synchronize configuration and code change?">
    See related guide:

    <Card title="How to synchronize configuration and code changes" icon="book-open-reader" href="https://www.aptible.com/docs/synchronized-deploys" />
  </Accordion>
</AccordionGroup>


# Image
Source: https://www.aptible.com/docs/core-concepts/apps/deploying-apps/image/overview

Learn about deploying Docker images on Aptible

# Overview

On Aptible, a [Docker image](https://docs.docker.com/get-started/overview/#images) is used to deploy app containers.

# Deploying with Git

Deploy with Git where you push source code (including a Dockerfile) via Git repository to Aptible, and the platform creates a Docker image on your behalf.

<Card title="Learn more about deploying with Git" icon="book" href="https://www.aptible.com/docs/dockerfile-deploy" />

# Deploy from Docker Image

Deploy from Docker Image where you deploy a Docker image that you have built yourself (e.g., in a CI environment), push it to a registry, and tell Aptible to fetch it from there.

<Card title="Learn more about deploying from Docker Image" icon="book" href="https://www.aptible.com/docs/direct-docker-image-deploy" />


# Linking Apps to Sources
Source: https://www.aptible.com/docs/core-concepts/apps/deploying-apps/linking-apps-to-sources



# Overview

Apps can be connected to their [Sources](/docs/core-concepts/observability/sources) to enable the Aptible dashboard to provide details about the code that is deployed in your infrastructure, enabling your team to answer the question "*what's deployed where?*".

When an App is connected to its Source, you'll see details about the currently-deployed revision (the git ref, SHA, commit message, and other information) in the header of the App Details page, as well as a running history of revision information on the Deployments tab.

# Sending Deployment Metadata to Aptible

To get started, you'll need to configure your deployment pipeline to send Source information when your App is deployed.

## Using the Aptible Deploy GitHub Action

> 📘 If you're using **version `v4` or later** of the official [Aptible Deploy GitHub Action](https://github.com/aptible/aptible-deploy-action), Source information is retrieved and sent automatically. No further configuration is required.

To set up a new Source for an App, visit the [Source Setup page](https://app.aptible.com/sources/setup) and follow the instructions. You will be presented with a GitHub Workflow that you can add to your repository.

## Using Another Deployment Strategy

The Sources feature is powered by [App configuration](/docs/core-concepts/apps/deploying-apps/configuration), so if you're using Terraform or your own custom scripts to deploy your app, you'll just need to send the following variables along with your deployment (note that **all of these variables are optional**):

* `APTIBLE_GIT_REPOSITORY_URL`, the browser-accessible URL of the git repository associated with the App.
  * Example: `https://github.com/example-org/example`.
* `APTIBLE_GIT_REF`, the branch name or tag of the revision being deployed.
  * Example: `release-branch-2024-01-01` or `v1.0.1`.
* `APTIBLE_GIT_COMMIT_SHA`, the 40-character git commit SHA.
  * Example: `2fa8cf206417ac18179f36a64b31e6d0556ff20684c1ad8d866569912bbf7235`.
* `APTIBLE_GIT_COMMIT_URL`, the browser-accessible URL of the commit.
  * Example: `https://github.com/example-org/example/commit/2fa8cf`.
* `APTIBLE_GIT_COMMIT_TIMESTAMP`, the ISO8601 timestamp of the git commit.
  * Example: `2024-01-01T12:00:00-04:00`.
* `APTIBLE_GIT_COMMIT_MESSAGE`, the full git commit message.
* (If deploying a Docker image) `APTIBLE_DOCKER_REPOSITORY_URL`, the browser-accessible URL of the Docker registry for the image being deployed.
  * Example: `https://hub.docker.com/repository/docker/example-org/example`

For example, if you're using the Aptible CLI to deploy your app, you might use a command like this:

```shell theme={null}
$ aptible deploy --app your-app \
    --docker-image=example-org/example:v1.0.1 \
    APTIBLE_GIT_REPOSITORY_URL="https://github.com/example/example" \
    APTIBLE_GIT_REF="$(git symbolic-ref --short -q HEAD || git describe --tags --exact-match 2> /dev/null)" \
    APTIBLE_GIT_COMMIT_SHA="$(git rev-parse HEAD)" \
    APTIBLE_GIT_COMMIT_URL="https://github.com/example/repo/commit/$(git rev-parse HEAD)" \
    APTIBLE_GIT_COMMIT_MESSAGE="$(git log -1 --pretty=%B)" \
    APTIBLE_GIT_COMMIT_TIMESTAMP="$(git log -1 --pretty=%cI)"
```


# Deploying Apps
Source: https://www.aptible.com/docs/core-concepts/apps/deploying-apps/overview

Learn about the components involved in deploying an Aptible app in seconds: images, services, and configurations

# Overview

On Aptible, developers can deploy code, and in seconds, the platform will transform their code into app containers with zero-downtime — completely abstracting the complexities of the underlying infrastructure.

Apps are made up of three components:

* **[An Image:](/docs/core-concepts/apps/deploying-apps/image/overview)** Deploy directly from a Docker image, or push your code to Aptible with `git push` and the platform will build a Docker image for you.
* **[Services:](/docs/core-concepts/apps/deploying-apps/services)** Services define how many containers Aptible will start for your app, what command they will run, and their Memory and CPU Limits.
* **[Configuration (optional):](/docs/core-concepts/apps/deploying-apps/configuration)** The configuration is a set of keys and values securely passed to the containers as environment variables. For example - secrets are passed as configurations.

# Get Started

If you are just getting started, [deploy a starter template.](/docs/getting-started/deploy-starter-template/overview)

# Integrating with CI/CD

Aptible integrates with several continuous integration services to make it easier to deploy on Aptible—whether migrating from another platform or deploying for the first time.

<CardGroup>
  <Card title="Browse CI/CD integrations" icon="arrow-up-right" href="https://www.aptible.com/docs/core-concepts/integrations/overview#developer-tools" />

  <Card title="How to deploy to Aptible from CI/CD" icon="book-open-reader" href="https://www.aptible.com/docs/continuous-integration-provider-deployment" />
</CardGroup>


# .aptible.yml
Source: https://www.aptible.com/docs/core-concepts/apps/deploying-apps/releases/aptible-yml



In addition to [Configuration variables read by Aptible](/docs/core-concepts/apps/deploying-apps/configuration), Aptible also lets you configure your [Apps](/docs/core-concepts/apps/overview) through a `.aptible.yml` file.

# Location

If you are using [deploying via Git](/docs/how-to-guides/app-guides/deploy-from-git), this file must be named `.aptible.yml` and located at the root of your repository.

If you are using [deploying via Docker image](/docs/how-to-guides/app-guides/migrate-dockerfile-to-direct-image-deploy), it must be located at `/.aptible/.aptible.yml` in your Docker image. See [Procfiles and `.aptible.yml` with deploying via Docker image](/docs/core-concepts/apps/deploying-apps/image/deploying-with-docker-image/procfile-aptible-yml-direct-docker-deploy) for more information.

# Structure

This file should be a `yaml` file containing any of the following configuration keys:

## `before_release`

<Warning>For now, this is an alias to `before_deploy`, but should be considered deprecated. If you're still using this key, please update!</Warning>

## `before_deploy`

`before_deploy` should be set to a list, e.g.:

```yaml theme={null}
before_deploy:
  - command1
  - command2
```

<Warning>If your Docker image has an `ENTRYPOINT`, Aptible will not use a shell to interpret your commands. Instead, the command is split according to shell rules, then simply passed to your Container's ENTRYPOINT as a series of arguments. In this case, using the form `sh -c 'command1 && command2'` or making use of a single wrapper script is required. See [How to define services](/docs/how-to-guides/app-guides/define-services#images-with-an-entrypoint) for additional details.</Warning>

The commands listed under `before_deploy` will run when you deploy your app, either via a `git push` (for [deploying via Git](/docs/how-to-guides/app-guides/deploy-from-git)) or using [`aptible deploy`](/docs/reference/aptible-cli/cli-commands/cli-deploy) (for [deploying via Docker image](/docs/how-to-guides/app-guides/migrate-dockerfile-to-direct-image-deploy)). However, they will *not* run when you execute [`aptible config:set`](/docs/reference/aptible-cli/cli-commands/cli-config-set), [`aptible restart`](/docs/reference/aptible-cli/cli-commands/cli-restart), etc.

`before_deploy` commands are executed in an isolated ephemeral [Container](/docs/core-concepts/architecture/containers/overview), before new [Release](/docs/core-concepts/apps/deploying-apps/releases/overview) Containers are launched. The commands are executed sequentially in the order that they are listed in the file.

If any of the `before_deploy` commands fail, Release Containers will not be launched and the operation will be rolled back.

This has several key implications:

* Any side effects of your `before_deploy` commands (such as database migrations) are guaranteed to have been completed before new Containers are launched for your app.
* Any changes made to the container filesystem by a `before_deploy` command (such as installing dependencies or pre-compiling assets) will **not** be reflected in the Release Containers. You should usually include such commands in your [Dockerfile](/docs/core-concepts/apps/deploying-apps/image/deploying-with-git/overview) instead.

As such, `before_deploy` commands are ideal for use cases such as:

* Automating database migrations
* Notifying an error tracking system that a new release is being deployed.

<Warning>There is a 30-minute timeout on `before_deploy` tasks. If you need to run something that takes longer, consider using [Ephemeral SSH Sessions](/docs/core-concepts/apps/connecting-to-apps/ssh-sessions).</Warning>

## After Success/Failure Hooks

Aptible provides multiple hook points for you to run custom code when certain operations succeed or fail.

Like `before_deploy`, commands are executed in an isolated ephemeral [Container](/docs/core-concepts/architecture/containers/overview). These commands are executed sequentially in the order that they are listed in the file.

**Success hooks** run after your Release Containers are launched and confirmed to be in good health. **Failure hooks** run if the operation needs to be rolled back.

<Note>Unlike `before_deploy`, command failures in these hooks do not result in the operation being rolled back.</Note>

<Warning>There is a 30-minute timeout on all hooks.</Warning>

The available hooks are:

* `after_deploy_success`
* `after_restart_success`
* `after_configure_success`
* `after_scale_success`
* `after_deploy_failure`
* `after_restart_failure`
* `after_configure_failure`
* `after_scale_failure`

As their names suggest, these hooks run during `deploy`, `restart`, `configure`, and `scale` operations.

In order to update your hooks, you must initiate a deploy with the new hooks added to your .aptible.yml.

Please note that due to their nature, **Failure hooks** are only updated after a successful deploy. This means, for example, that if you currently have an `after_deploy_failure` hook A, and are updating it to B, it will only take effect after the deploy operation completes. If the deploy operation were to fail, then the `after_deploy_failure` hook A would run, not B. In a similar vein, Failure hooks use your **previous** image to run commands, not the current image being deployed. As such, it would not have any new code available to it.


# Releases
Source: https://www.aptible.com/docs/core-concepts/apps/deploying-apps/releases/overview



Whenever you deploy, restart, configure, scale, etc. your App, a new set of [Containers](/docs/core-concepts/architecture/containers/overview) will be launched to replace the existing ones for each of your App's [Services](/docs/core-concepts/apps/deploying-apps/services).

This set of Containers is referred to as a Release. The Containers themselves are referred to as Release Containers, as opposed to the ephemeral containers created by e.g. [`before_release`](/docs/core-concepts/apps/deploying-apps/releases/aptible-yml#before-release) commands or [Ephemeral SSH Sessions](/docs/core-concepts/apps/connecting-to-apps/ssh-sessions).

> 📘 Each one of your App's Services gets a new Release when you deploy, etc. In other words, Releases are Scoped to Services, not Apps. This isn't very important, but it'll help you better understand how certain [Aptible Metadata](/docs/core-concepts/architecture/containers/overview#aptible-metadata) variables work.

# Lifecycle

Aptible will adopt a deployment strategy on a Service-by-Service basis.

The exact deployment strategy Aptible chooses for a given Service depends on whether the Service has any [Endpoints](/docs/core-concepts/apps/connecting-to-apps/app-endpoints/overview) associated with it:

> 📘 In any cases, new Containers are always launched *after* [`before_release`](/docs/core-concepts/apps/deploying-apps/releases/aptible-yml#before-release) commands have completed.

## Services without Endpoints

Services without Endpoints (also known as *Background Services*) are deployed with **zero overlap**: the existing Containers are stopped before new Containers are launched.

Alternatively, you can force **zero downtime** deploys either in the UI in the Service Settings area, [aptible-cli services:settings](/docs/reference/aptible-cli/cli-commands/cli-services-settings), or via our [Terraform Provider](https://registry.terraform.io/providers/aptible/aptible/latest/docs).
When this is enabled, we rely on [Docker Healthchecks](https://docs.docker.com/reference/dockerfile/#healthcheck) to ensure your containers are healthy before cutting over.
If you do not wish to use docker healthchecks, you may enable **simple healthchecks** for your service, which will instead ensure the container can remain up for 30 seconds before cutting over.
<Warning>Please read [Concurrent Releases](#concurrent-releases) for caveats to this deployment strategy</Warning>

### Docker Healthchecks

Since Docker Healthchecks affect your entire image and not just a single service, you MUST write a healthcheck script similar to the following:

```bash theme={null}
#!/bin/bash

case $APTIBLE_PROCESS_TYPE in
  "web" | "ui" )
      exit 0 # We do not use docker healthchecks for services with endpoints
      ;;
  "sidekiq-long-jobs" )
      # healthcheck-for-this-service
      ;;
  "cmd" )
      # yet another healthcheck
      ;;
  * )
    # So you don't ever accidentally enable zero-downtime on a service without defining a health check
    echo "Unexpected process type $APTIBLE_PROCESS_TYPE"
    exit 1
      ;;
esac
```

<img alt="Service Settings UI" />

## Services with Endpoints

Services with Endpoints (also known as *Foreground Services*) are deployed with **minimal** (for [TLS Endpoints](/docs/core-concepts/apps/connecting-to-apps/app-endpoints/tls-endpoints) and [TCP Endpoints](/docs/core-concepts/apps/connecting-to-apps/app-endpoints/tcp-endpoints)) or **zero downtime** (for [HTTP(S) Endpoints](/docs/core-concepts/apps/connecting-to-apps/app-endpoints/https-endpoints/overview)): new Containers are launched and start accepting traffic before the existing Containers are shut down.

<Warning>
  Services with an attached [Persistent Disk](/docs/core-concepts/apps/persistent-disks) cannot be deployed with zero downtime, regardless of endpoint type or zero-downtime settings. The disk can only be mounted into one container at a time, so deploys (and any operation that recycles the container, such as a restart, scale, configuration change, or attaching, detaching, or resizing the disk) follow a stop-then-start pattern: the existing container is stopped, the disk is unmounted, the new container is started, and the disk is re-mounted. Plan for a brief interruption on every deploy of a Service with a Persistent Disk.
</Warning>

Specifically, the process is:

1. Launch new Containers.

2. Wait for the new Containers to pass [Health Checks](/docs/core-concepts/apps/connecting-to-apps/app-endpoints/https-endpoints/health-checks) (only for [HTTP(S) Endpoints](/docs/core-concepts/apps/connecting-to-apps/app-endpoints/https-endpoints/overview)).

3. Register the new Containers with the Endpoint's load balancer. Wait for registration to complete.

4. Deregister the old Containers from the Endpoint's load balancer. Wait for deregistration to complete (in-flight requests are given 15 seconds to complete).

5. Shutdown the old Containers.

### Concurrent Releases

<img alt="" />

> ❗️ An important implication of zero-downtime deployments is that you'll have Containers from two different releases accepting traffic at the same time, so make sure you design your apps accordingly!

> For example, if you are running database migrations as part of your deploy, you need to design your migrations so that your existing Containers will be able to continue working with the database structure that results from running migrations.

> Often, this means you might need to apply complex migrations in multiple steps.

## Graceful Stop of Old Release Containers

When we stop the containers associated with the older release, a `SIGTERM` is initially sent to the main process within your container. After a certain grace period (by default 10 seconds), a `SIGKILL` is then sent to terminate the process regardless of if it is still running. You can customize this stop timeout grace period before the `SIGKILL` is sent by editing the stop timeout associated with the service, either in the UI (in the service Settings tab), in the CLI, or with terraform.

For example, your worker application may want to capture `SIGTERM` signals and put work back onto a queue before exiting cleanly to ensure jobs in process get picked back up by the new release containers. For services without endpoints that are not configured to use zero downtime deployment, we do wait for all containers to exit before starting up new containers, so for the duration of the time it takes to stop, there would be no containers processing work. Therefore it is recommended to keep this timeout as short as possible, or use zero downtime if possible.

However, note that your operations will wait on the containers to stop, so increasing the timeouts and having containers fail to exit quickly will increase the time taken for deploy, restart, configure, scale, etc. Operations are run sequentially against a given resource, so increasing the time of an operation could delay execution of further operations run against that same application or service.

The maximum time allowed for configurable stop timeout is 15 minutes.


# Services
Source: https://www.aptible.com/docs/core-concepts/apps/deploying-apps/services



<img alt="" />

# Overview

Services determine the number of Containers of your App and the memory and CPU limits for your app. An app can have multiple services.

Services are defined one of two ways:

* **Single Implicit Service:** By default, the platform will create a single implicit cmd service defined by your image’s `cmd` or `ENTRYPOINT`.
* **Explicit Services:** Alternatively, you can define one or more explicit services using a Procfile. This allows you to specify a command for each service. Each service is scaled independently.

# FAQ

<AccordionGroup>
  <Accordion title="How do I define Services">
    See related guide

    <Card title="How to define Services" icon="book-open-reader" href="https://www.aptible.com/docs/how-to-guides/app-guides/define-services" />
  </Accordion>

  <Accordion title="Can Services be scaled indepedently?">
    Yes, all App Services are scaled independently
  </Accordion>
</AccordionGroup>


# Managing Apps
Source: https://www.aptible.com/docs/core-concepts/apps/managing-apps

Learn how to manage Aptible Apps

# Overview

Aptible makes managing your application simple. Whether you're using the Aptible Dashboard, CLI, or Terraform, you have full control over your App’s lifecycle without needing to worry about the underlying infrastructure.

# Learn More

<AccordionGroup>
  <Accordion title="Manually Scaling Apps">
    <Frame>
      <img alt="scaling" />
    </Frame>

    Apps can be manually scaled both horizontially (number of containers) and vertically (RAM/CPU) can be scaled on-demand with zero downtime deployments. Refer to [App Scaling](/docs/core-concepts/scaling/app-scaling) for more information.
  </Accordion>

  <Accordion title="Autoscaling Apps">
    Read more in the [App Scaling page](/docs/core-concepts/scaling/app-scaling)
  </Accordion>

  <Accordion title="Restarting Apps">
    Apps can be restarted the following ways:

    * Using the [aptible restart](/docs/reference/aptible-cli/cli-commands/cli-restart) command
    * Within the Aptible Dashboard, by:

      * Navigating to the app
      * Selecting the Settings tab
      * Selecting Restart

      Like all [Releases](/docs/core-concepts/apps/deploying-apps/releases/overview), when Apps are restarted, a new set of [Containers](/docs/core-concepts/architecture/containers/overview) will be launched to replace the existing ones for each of your App's [Services](/docs/core-concepts/apps/deploying-apps/services).
  </Accordion>

  <Accordion title="Achieving High Availability">
    <Note> High Availability Apps are only available on [Production and Enterprise](https://www.aptible.com/pricing)[ plans.](https://www.aptible.com/pricing)</Note>

    Apps scaled to 2 or more Containers are automatically deployed in a high-availability configuration, with Containers deployed in separate [AWS Availability Zones](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/using-regions-availability-zones.html).
  </Accordion>

  <Accordion title="Renaming Apps">
    An App can be renamed in the following ways:

    * Using the [`aptible apps:rename`](/docs/reference/aptible-cli/cli-commands/cli-apps-rename) command
    * Using the Aptible [Terraform Provider](https://registry.terraform.io/providers/aptible/aptible/latest/docs)

    For the change to take effect, the App must be restarted.

    <Warning>App handles cannot start with "internal-" or "sg-" because applications with these prefixes cannot have [Endpoints](/docs/core-concepts/apps/connecting-to-apps/app-endpoints/overview) allocated due to AWS limitations.</Warning>
  </Accordion>

  <Accordion title="Deprovisioning an App">
    Apps can be deleted/deprovisioned using one of these three methods:

    * Within the Aptible Dashboard:
      * Selecting the Environment in which the App lives
      * Selecting the **Apps** tab
      * Selecting the given App
      * Selecting the **Deprovision** tab
    * Using the [`aptible apps:deprovision`](/docs/reference/aptible-cli/cli-commands/cli-apps-deprovision) command
    * Using the Aptible [Terraform Provider](https://registry.terraform.io/providers/aptible/aptible/latest/docs)
  </Accordion>
</AccordionGroup>


# Apps
Source: https://www.aptible.com/docs/core-concepts/apps/overview



<Frame>
  <img alt="Apps Overview" />
</Frame>

## Overview

Aptible is a platform that simplifies the deployment and management of applications, abstracting away the complexities of the underlying infrastructure for development teams. Here are the key features and capabilities that Aptible provides to achieve this:

1. **Simplified and Flexible Deployment:** You can deploy your code to app containers in seconds using Aptible. You have the option to [deploy via Git](https://www.aptible.com/docs/dockerfile-deploy) or [deploy via Docker Image](https://www.aptible.com/docs/direct-docker-image-deploy). Define your [services](https://www.aptible.com/docs/services) and [configurations](https://www.aptible.com/docs/configuration), and let the platform handle the deployment process and provisioning of the underlying infrastructure. Integrate with popular [CI/CD tools](/docs/how-to-guides/app-guides/how-to-deploy-aptible-ci-cd) like GitHub Actions, CircleCI, and GitLab CI for automated deployments.
2. **Easy Connectivity:** Aptible offers multiple methods for connecting to your deployed applications. Users can access their apps through public URLs, ephemeral sessions, or outbound IP addresses.
3. **Scalability Options:** Easily [scale an App](/docs/core-concepts/scaling/app-scaling) to add more containers to your application to handle the increased load, or vertically to allocate additional resources like RAM and CPU to meet performance requirements. Scale manually, or automatically with [horizontal autoscaling](/docs/core-concepts/scaling/app-scaling#horizontal-autoscaling) (based on CPU usage) and [vertical autoscaling](/docs/core-concepts/scaling/app-scaling#vertical-autoscaling) (based on memory and CPU usage). Aptible offers various [container profiles](/docs/core-concepts/scaling/container-profiles), allowing you to fine-tune resource allocation for optimal performance.
4. **High Availability:** Apps hosted on Aptible are designed to maintain high availability. Apps are deployed with zero downtime, and when scaled to two or more containers, the platform automatically distributes them across multiple availability zones. (Services with an attached [Persistent Disk](/docs/core-concepts/apps/persistent-disks) are an exception: they run on a single container and incur a brief interruption on every deploy.)

## Learn more using Apps on Aptible

<CardGroup>
  <Card title="Deploying Apps" icon="book" href="https://www.aptible.com/docs/core-concepts/apps/deploying-apps/overview">
    Learn to deploy your code into Apps with an image, Services, and Configuration
  </Card>

  <Card title="Connecting to Apps" icon="book" href="https://www.aptible.com/docs/core-concepts/apps/connecting-to-apps/overview">
    Learn to expose your App to the internet with Endpoints and connect with ephemeral SSH sessions
  </Card>

  <Card title="Managing Apps" icon="book" href="https://www.aptible.com/docs/core-concepts/apps/managing-apps">
    Learn to scale, restart, rename, restart, and delete your Apps
  </Card>
</CardGroup>

## Explore Starter Templates

<CardGroup>
  <Card title="Deploy your code" icon="globe" href="https://www.aptible.com/docs/custom-code-quickstart">
    <Badge>Custom Code</Badge>
  </Card>

  <Card title="Ruby Template" href="https://www.aptible.com/docs/ruby-quickstart" icon={<svg width="30" height="30" viewBox="0 0 256 255" xmlns="http://www.w3.org/2000/svg"><path d="M197.467 167.764l-145.52 86.41 188.422-12.787L254.88 51.393l-57.414 116.37z" fill="#CC342D"/><path d="M240.677 241.257L224.482 129.48l-44.113 58.25 60.308 53.528z" fill="#A11401"/><path d="M240.896 241.257l-118.646-9.313-69.674 21.986 188.32-12.673z" fill="#A11401"/><path d="M52.744 253.955l29.64-97.1L17.16 170.8l35.583 83.154z" fill="#E05A4D"/><path d="M180.358 188.05L153.085 81.226l-78.047 73.16 105.32 33.666z" fill="#CC342D"/><path d="M248.693 82.73l-73.777-60.256-20.544 66.418 94.321-6.162z" fill="#E05A4D"/><path d="M214.191.99L170.8 24.97 143.424.669l70.767.322z" fill="#CC342D"/><path d="M2.496 129.48l14.794 41.963 64.283-14.422 73.39-68.207 20.712-65.787L143.063 0 87.618 20.75C70.149 37 36.252 69.146 35.03 69.75c-1.21.618-22.384 40.639-32.534 59.73z" fill="#fff"/><path d="M54.442 54.094c37.86-37.538 86.667-59.716 105.397-40.818 18.72 18.898-1.132 64.823-38.992 102.349-37.86 37.525-86.062 60.925-104.78 42.027-18.73-18.885.515-66.032 38.375-103.558z" fill="#CC342D"/><path d="M52.744 253.916l29.408-97.409 97.665 31.376c-35.312 33.113-74.587 61.106-127.073 66.033z" fill="#9B1209"/><path d="M155.092 88.622l25.073 99.313c29.498-31.016 55.972-64.36 68.938-105.603l-94.01 6.29z" fill="#AA1401"/><path d="M248.847 82.833c10.035-30.282 12.35-73.725-34.966-81.791l-38.825 21.445 73.791 60.346z" fill="#B31000"/><path d="M0 202.935c1.39 49.979 37.448 50.724 52.808 51.162l-35.48-82.86L0 202.935z" fill="#9E1209"/></svg>}>
    <Badge>Sample Code</Badge>
  </Card>

  <Card
    title="NodeJS Template"
    href="https://www.aptible.com/docs/node-js-quickstart"
    icon={
<svg xmlns="http://www.w3.org/2000/svg" width="30" height="30" viewBox="0 0 58 64" fill="none">
<path d="M26.3201 0.681001C27.9201 -0.224999 29.9601 -0.228999 31.5201 0.681001L55.4081 14.147C56.9021 14.987 57.9021 16.653 57.8881 18.375V45.375C57.8981 47.169 56.8001 48.871 55.2241 49.695L31.4641 63.099C30.6514 63.5481 29.7333 63.7714 28.8052 63.7457C27.877 63.7201 26.9727 63.4463 26.1861 62.953L19.0561 58.833C18.5701 58.543 18.0241 58.313 17.6801 57.843C17.9841 57.435 18.5241 57.383 18.9641 57.203C19.9561 56.887 20.8641 56.403 21.7761 55.891C22.0061 55.731 22.2881 55.791 22.5081 55.935L28.5881 59.451C29.0221 59.701 29.4621 59.371 29.8341 59.161L53.1641 45.995C53.4521 45.855 53.6121 45.551 53.5881 45.235V18.495C53.6201 18.135 53.4141 17.807 53.0881 17.661L29.3881 4.315C29.2515 4.22054 29.0894 4.16976 28.9234 4.16941C28.7573 4.16905 28.5951 4.21912 28.4581 4.313L4.79207 17.687C4.47207 17.833 4.25207 18.157 4.29207 18.517V45.257C4.26407 45.573 4.43207 45.871 4.72207 46.007L11.0461 49.577C12.2341 50.217 13.6921 50.577 15.0001 50.107C15.5725 49.8913 16.0652 49.5058 16.4123 49.0021C16.7594 48.4984 16.9443 47.9007 16.9421 47.289L16.9481 20.709C16.9201 20.315 17.2921 19.989 17.6741 20.029H20.7141C21.1141 20.019 21.4281 20.443 21.3741 20.839L21.3681 47.587C21.3701 49.963 20.3941 52.547 18.1961 53.713C15.4881 55.113 12.1401 54.819 9.46407 53.473L2.66407 49.713C1.06407 48.913 -0.00993076 47.185 6.9243e-05 45.393V18.393C0.0067219 17.5155 0.247969 16.6557 0.698803 15.9027C1.14964 15.1498 1.79365 14.5312 2.56407 14.111L26.3201 0.681001ZM33.2081 19.397C36.6621 19.197 40.3601 19.265 43.4681 20.967C45.8741 22.271 47.2081 25.007 47.2521 27.683C47.1841 28.043 46.8081 28.243 46.4641 28.217C45.4641 28.215 44.4601 28.231 43.4561 28.211C43.0301 28.227 42.7841 27.835 42.7301 27.459C42.4421 26.179 41.7441 24.913 40.5401 24.295C38.6921 23.369 36.5481 23.415 34.5321 23.435C33.0601 23.515 31.4781 23.641 30.2321 24.505C29.2721 25.161 28.9841 26.505 29.3261 27.549C29.6461 28.315 30.5321 28.561 31.2541 28.789C35.4181 29.877 39.8281 29.789 43.9141 31.203C45.6041 31.787 47.2581 32.923 47.8381 34.693C48.5941 37.065 48.2641 39.901 46.5781 41.805C45.2101 43.373 43.2181 44.205 41.2281 44.689C38.5821 45.279 35.8381 45.293 33.1521 45.029C30.6261 44.741 27.9981 44.077 26.0481 42.357C24.3801 40.909 23.5681 38.653 23.6481 36.477C23.6681 36.109 24.0341 35.853 24.3881 35.883H27.3881C27.7921 35.855 28.0881 36.203 28.1081 36.583C28.2941 37.783 28.7521 39.083 29.8161 39.783C31.8681 41.107 34.4421 41.015 36.7901 41.053C38.7361 40.967 40.9201 40.941 42.5101 39.653C43.3501 38.919 43.5961 37.693 43.3701 36.637C43.1241 35.745 42.1701 35.331 41.3701 35.037C37.2601 33.737 32.8001 34.209 28.7301 32.737C27.0781 32.153 25.4801 31.049 24.8461 29.351C23.9601 26.951 24.3661 23.977 26.2321 22.137C28.0321 20.307 30.6721 19.601 33.1721 19.349L33.2081 19.397Z" fill="#8CC84B"/></svg>
}
  >
    <Badge>Sample Code</Badge>
  </Card>

  <Card
    title="Django Template"
    href="https://www.aptible.com/docs/python-quickstart"
    icon={
<svg width="30" height="30" viewBox="0 0 256 326" xmlns="http://www.w3.org/2000/svg" preserveAspectRatio="xMinYMin meet"><g fill="#2BA977"><path d="M114.784 0h53.278v244.191c-27.29 5.162-47.38 7.193-69.117 7.193C33.873 251.316 0 222.245 0 166.412c0-53.795 35.93-88.708 91.608-88.708 8.64 0 15.222.68 23.176 2.717V0zm1.867 124.427c-6.24-2.038-11.382-2.717-17.965-2.717-26.947 0-42.512 16.437-42.512 45.243 0 28.046 14.88 43.532 42.17 43.532 5.896 0 10.696-.332 18.307-1.351v-84.707z"/><path d="M255.187 84.26v122.263c0 42.105-3.154 62.353-12.411 79.81-8.64 16.783-20.022 27.366-43.541 39.055l-49.438-23.297c23.519-10.93 34.901-20.588 42.17-35.327 7.61-15.072 10.01-32.529 10.01-78.445V84.261h53.21zM196.608 0h53.278v54.135h-53.278V0z"/></g></svg>
}
  >
    <Badge>Sample Code</Badge>
  </Card>

  <Card
    title="Laravel Template"
    href="https://www.aptible.com/docs/php-quickstart"
    icon={
<svg height="30" viewBox="0 -.11376601 49.74245785 51.31690859" width="30" xmlns="http://www.w3.org/2000/svg"><path d="m49.626 11.564a.809.809 0 0 1 .028.209v10.972a.8.8 0 0 1 -.402.694l-9.209 5.302v10.509c0 .286-.152.55-.4.694l-19.223 11.066c-.044.025-.092.041-.14.058-.018.006-.035.017-.054.022a.805.805 0 0 1 -.41 0c-.022-.006-.042-.018-.063-.026-.044-.016-.09-.03-.132-.054l-19.219-11.066a.801.801 0 0 1 -.402-.694v-32.916c0-.072.01-.142.028-.21.006-.023.02-.044.028-.067.015-.042.029-.085.051-.124.015-.026.037-.047.055-.071.023-.032.044-.065.071-.093.023-.023.053-.04.079-.06.029-.024.055-.05.088-.069h.001l9.61-5.533a.802.802 0 0 1 .8 0l9.61 5.533h.002c.032.02.059.045.088.068.026.02.055.038.078.06.028.029.048.062.072.094.017.024.04.045.054.071.023.04.036.082.052.124.008.023.022.044.028.068a.809.809 0 0 1 .028.209v20.559l8.008-4.611v-10.51c0-.07.01-.141.028-.208.007-.024.02-.045.028-.068.016-.042.03-.085.052-.124.015-.026.037-.047.054-.071.024-.032.044-.065.072-.093.023-.023.052-.04.078-.06.03-.024.056-.05.088-.069h.001l9.611-5.533a.801.801 0 0 1 .8 0l9.61 5.533c.034.02.06.045.09.068.025.02.054.038.077.06.028.029.048.062.072.094.018.024.04.045.054.071.023.039.036.082.052.124.009.023.022.044.028.068zm-1.574 10.718v-9.124l-3.363 1.936-4.646 2.675v9.124l8.01-4.611zm-9.61 16.505v-9.13l-4.57 2.61-13.05 7.448v9.216zm-36.84-31.068v31.068l17.618 10.143v-9.214l-9.204-5.209-.003-.002-.004-.002c-.031-.018-.057-.044-.086-.066-.025-.02-.054-.036-.076-.058l-.002-.003c-.026-.025-.044-.056-.066-.084-.02-.027-.044-.05-.06-.078l-.001-.003c-.018-.03-.029-.066-.042-.1-.013-.03-.03-.058-.038-.09v-.001c-.01-.038-.012-.078-.016-.117-.004-.03-.012-.06-.012-.09v-21.483l-4.645-2.676-3.363-1.934zm8.81-5.994-8.007 4.609 8.005 4.609 8.006-4.61-8.006-4.608zm4.164 28.764 4.645-2.674v-20.096l-3.363 1.936-4.646 2.675v20.096zm24.667-23.325-8.006 4.609 8.006 4.609 8.005-4.61zm-.801 10.605-4.646-2.675-3.363-1.936v9.124l4.645 2.674 3.364 1.937zm-18.422 20.561 11.743-6.704 5.87-3.35-8-4.606-9.211 5.303-8.395 4.833z" fill="#ff2d20"/></svg>
}
  >
    <Badge>Sample Code</Badge>
  </Card>

  <Card title="Python Template" href="https://www.aptible.com/docs/deploy-demo-app" icon={<svg width="30" height="30" viewBox="0 0 256 255" xmlns="http://www.w3.org/2000/svg"><path d="M126.916.072c-64.832 0-60.784 28.115-60.784 28.115l.072 29.128h61.868v8.745H41.631S.145 61.355.145 126.77c0 65.417 36.21 63.097 36.21 63.097h21.61v-30.356s-1.165-36.21 35.632-36.21h61.362s34.475.557 34.475-33.319V33.97S194.67.072 126.916.072zM92.802 19.66a11.12 11.12 0 0 1 11.13 11.13 11.12 11.12 0 0 1-11.13 11.13 11.12 11.12 0 0 1-11.13-11.13 11.12 11.12 0 0 1 11.13-11.13z" fill="#3776AB"/><path d="M128.757 254.126c64.832 0 60.784-28.115 60.784-28.115l-.072-29.127H127.6v-8.745h86.441s41.486 4.705 41.486-60.712c0-65.416-36.21-63.096-36.21-63.096h-21.61v30.355s1.165 36.21-35.632 36.21h-61.362s-34.475-.557-34.475 33.32v56.013s-5.235 33.897 62.518 33.897zm34.114-19.586a11.12 11.12 0 0 1-11.13-11.13 11.12 11.12 0 0 1 11.13-11.131 11.12 11.12 0 0 1 11.13 11.13 11.12 11.12 0 0 1-11.13 11.13z" fill="#FFD43B"/></svg>}>
    <Badge>Sample Code</Badge>
  </Card>
</CardGroup>


# Persistent Disks for Apps
Source: https://www.aptible.com/docs/core-concepts/apps/persistent-disks

Attach a persistent disk to an App Service to retain data across deploys, restarts, and container recycles.

## Overview

Persistent Disks let an App [Service](/docs/core-concepts/apps/deploying-apps/services) keep state on disk across deploys, restarts, and container recycles. They are the recommended option for workloads that need durable local storage but don't fit into one of Aptible's [Managed Databases](/docs/core-concepts/managed-databases/overview), for example, JupyterLab notebooks, or self-hosting third-party tools that require local disk.

By default, App [Containers](/docs/core-concepts/architecture/containers/overview) run with an **ephemeral filesystem**: any data written outside of an attached Persistent Disk is lost when the container is recycled. A Persistent Disk is a separately-provisioned volume that is mounted into the container and survives the container's lifecycle. Under the hood, each Persistent Disk is an AWS EBS gp3 volume, and all Persistent Disks are encrypted at rest using AWS EBS volume encryption.

## When to use a Persistent Disk

Reach for a Persistent Disk when:

* You need a small amount of durable local state, and a [Managed Database](/docs/core-concepts/managed-databases/overview) is the wrong shape for the data (for example, a working directory for a stateful background job, or a self-managed search index).
* The data does not need to be shared across multiple replicas.
* You can tolerate the operational tradeoffs described in [Limitations](#limitations) below. Most importantly, the Service is pinned to a single container and a single Availability Zone.

Persistent Disks are not for:

* **Shared, multi-writer storage across containers.** A disk attaches to one Service at a time, and that Service is pinned to a single container, so multiple processes on different containers cannot read or write the same disk.
* **Automatic backups.** Aptible does not snapshot Persistent Disks. Backing up disk contents is your responsibility.
* **Cross-AZ failover.** A disk lives in one Availability Zone, and the Service that mounts it runs in that same AZ for the life of the disk.
* **Object-store-style large-file workloads.** For bulk file storage, media, or shared blobs, AWS S3 (or another object store) is a better fit.
* **Self-hosted databases.** Use a [Managed Database](/docs/core-concepts/managed-databases/overview) instead.

If you need shared, multi-writer storage, a managed object store (for example, AWS S3) or a [Managed Database](/docs/core-concepts/managed-databases/overview) is usually a better fit.

## Creating and attaching a disk

The Aptible Dashboard offers creating a Persistent Disk and attaching it to a Service as a single flow. Under the hood, these are two separate operations: the create can succeed even if the attach fails, in which case the disk exists unattached and can be attached afterward. You specify:

* The **Service** the disk will attach to.
* The **size** of the disk in GB.
* The **mount point** inside the container (for example, `/var/data`).

Once attached, the Service is restarted so the new container can mount the volume. The Service's container is scheduled into the same Availability Zone as the disk (see [Limitations](#limitations)).

<Note>
  A Service can have at most one Persistent Disk attached, and a disk can be attached to only one Service at a time. Each attachment exposes the disk at exactly one mount point inside the Service's container.
</Note>

### Mount points

The mount point is the path inside the container at which the disk is exposed. It must be an absolute path, and it should not collide with a path that is populated by your container image (otherwise, the image contents at that path will be hidden by the mount). A common choice is a dedicated directory like `/var/data` or `/mnt/data`.

The mount point is set when the disk is first attached and cannot be changed in place. To move data to a new mount point, detach the disk, re-attach it at the new path, and update your application code.

## Detaching a disk

A disk can be detached from a Service from the Aptible Dashboard. Detaching stops the running container, unmounts the disk, and starts a new container without the disk attached. The disk itself is preserved and can later be re-attached to a Service in the same [Environment](/docs/core-concepts/architecture/environments) as the disk or destroyed.

Detaching restarts the Service's container so it comes back up without the disk mounted. Plan for a brief interruption when you detach.

Destroying a disk permanently deletes its contents. There is no undo: make sure any data you want to keep is backed up before you destroy a disk.

<Warning>
  Aptible does not take backups of Persistent Disks. Unlike [Managed Databases](/docs/core-concepts/managed-databases/overview), Persistent Disks have no automatic backup system. You are responsible for backing up the contents of a disk yourself.
</Warning>

## Resizing a disk

A Persistent Disk can be resized **up** at any time from the Aptible Dashboard. Increasing the size grows the volume in place: you do not need to detach the disk or create a new one, and the data on the disk is preserved. Like attaching and detaching, resizing requires a brief restart of the Service so the new container can use the resized volume.

A disk **cannot** be made smaller. If you need to reduce the size of a disk, create a new, smaller disk, copy your data over, and detach and destroy the original.

## Limitations

Persistent Disks introduce some constraints that don't apply to stateless App Services. Plan for these before you adopt them.

### Single Availability Zone

A Persistent Disk lives in a single Availability Zone. The Service's container must run in the same AZ as its disk, so the Service is effectively pinned to that AZ for the life of the disk. If the AZ becomes unavailable, the Service will be unavailable until the AZ recovers.

If your workload requires multi-AZ resilience for the data on disk, use a [Managed Database](/docs/core-concepts/managed-databases/overview) or an external object store instead.

### Single container per Service

A Service with a Persistent Disk attached **must be scaled to a container count of 1**. You cannot scale horizontally: the disk cannot be shared across multiple containers, and Aptible will not let you increase the container count while a disk is attached.

If you need to scale a workload horizontally, split the durable state out (into a [Managed Database](/docs/core-concepts/managed-databases/overview), an object store, or a separate Service) so the horizontally-scaled Service can stay stateless.

See [App Scaling](/docs/core-concepts/scaling/app-scaling) for more on how Services are scaled.

### No zero-downtime deploys

A normal Aptible App Service is deployed with a zero-downtime [Release](/docs/core-concepts/apps/deploying-apps/releases/overview): a new container is started, traffic shifts to it, and the old container is stopped only after the new one is healthy.

A Service with a Persistent Disk **cannot** deploy with zero downtime. The disk can only be mounted into one container at a time, so deploys (and any operation that recycles the container, such as a restart, scale, configuration change, or attaching, detaching, or resizing the disk) follow a stop-then-start pattern: the existing container is stopped, the disk is unmounted, the new container is started, and the disk is re-mounted.

Plan for a brief interruption on every deploy of a Service with a Persistent Disk. See [Releases](/docs/core-concepts/apps/deploying-apps/releases/overview) for more on the deploy lifecycle.

## Permissions

Persistent Disks are managed with the same environment-scoped permissions as your other resources, such as Apps and Databases. There is no special or privileged access required. Creating a disk and attaching it to a Service require the **Deployment** permission. Resizing or modifying a disk requires the **Deployment** or **Ops** permission, and detaching a disk requires the **Deployment** or **Destruction** permission. Deleting a disk requires the **Destruction** permission.

See the [Roles & Permissions matrix](/docs/core-concepts/security-compliance/access-permissions#full-permission-type-matrix) for the full action-to-permission mapping.

## Pricing

Persistent Disks are billed at **\$0.20 per GB per month** of provisioned capacity, independent of the Service they are attached to. Billing is based on the size you provision, not the amount of data you store.

A disk bills for as long as it exists, whether or not it is currently attached to a Service. Detaching a disk preserves its data and continues to bill for it. Only destroying the disk stops billing.

Disks are provisioned as gp3 volumes with a baseline of 3,000 IOPS at no additional charge; IOPS and throughput are not user-configurable. If a disk is provisioned with IOPS above the baseline, the additional IOPS are billed at **\$0.01 per provisioned IOPS per month**. Most disks run at the baseline and incur no IOPS charge.

## Related

* [Managing Apps](/docs/core-concepts/apps/managing-apps)
* [App Scaling](/docs/core-concepts/scaling/app-scaling)
* [Releases](/docs/core-concepts/apps/deploying-apps/releases/overview)
* [Managed Databases](/docs/core-concepts/managed-databases/overview) for multi-writer or multi-AZ durable storage


# Container Recovery
Source: https://www.aptible.com/docs/core-concepts/architecture/containers/container-recovery



When [Containers](/docs/core-concepts/architecture/containers/overview) on Aptible exit unexpectedly (i.e., Aptible did not terminate them as part of a deploy or restart), they are automatically restarted. This feature is called Container Recovery. For most apps, Aptible will automatically restart containers in the event of a crash without requiring user action.

# Overview

When Containers exit, Aptible automatically restarts them from a pristine state. As a result, any changes to the filesystem will be undone (e.g., PID files will be deleted, etc.). As a user, the implication is that if a Container starts properly, Aptible can automatically recover it. To modify this behavior, see [Disabling filesystem wipes](#disabling-filesystem-wipes) below.

Whenever a Container exits and Container Recovery is initiated, Aptible logs the following messages and forwards them to your Log Drains. Note that these logs may not be contiguous; there may be additional log lines between them.

```
container has exited
container recovery initiated
container has started
```

If you wish to set up a log-based alert whenever a Container crashes, we recommend doing so based on the string `container recovery initiated`. This is because the lines `container has started` and `container has exited` will be logged during the normal, healthy [Release Lifecycle](/docs/core-concepts/apps/deploying-apps/releases/overview).

If an App is continuously restarting, Aptible will throttle recovery to a rate of one attempt every 2 minutes.

# Cases where Container Recovery will not work

Container Recovery restarts *Containers* that exit, so if an app crashes but the Container does not exit, then Container Recovery can't help.

Here's an example [Procfile](/docs/how-to-guides/app-guides/define-services) demonstrating this issue:

```yaml theme={null}
app: (my-app &) && tail -F log/my-app.log
```

In this case, since `my-app` is running in the background, the Container will not exit when `my-app` exits. Instead, it would exit if `tail` exited.

To ensure Container Recovery effectively keeps an App up, make sure that:

* Each Container is only running one App.
* The one App each Container is supposed to run is running in the foreground.

For example, rewrite the above Procfile like so:

```yaml theme={null}
app: (tail -F log/my-app.log &) && my-app
```

Use a dedicated process manager in a Container, such as [Forever](https://github.com/foreverjs/forever) or [Supervisord](http://supervisord.org/), if multiple processes need to run in a Container or something else needs to run in the foreground.

Contact [Aptible Support](/docs/how-to-guides/troubleshooting/aptible-support) when in doubt.

# Disabling filesystem wipes

Container Recovery automatically restarting containers with a pristine filesystem maximizes the odds of a Container coming back up when recovered and mimics what happens when restarting an App using [`aptible restart`](/docs/reference/aptible-cli/cli-commands/cli-restart).

Set the `APTIBLE_DO_NOT_WIPE` [Configuration](/docs/core-concepts/apps/deploying-apps/configuration) variable on an App to any non-null value (e.g., set it to `1`) to prevent the filesystem from being wiped (assuming it is designed to handle being restarted properly).


# Containers
Source: https://www.aptible.com/docs/core-concepts/architecture/containers/overview



Aptible deploys all resources in Containers.

# Container Command

Containers run the command specified by the [Service](/docs/core-concepts/apps/deploying-apps/services) they belong to:

* If the service is an [Implicit Service](/docs/how-to-guides/app-guides/define-services#implicit-service-cmd), then that command is the [Image](/docs/core-concepts/apps/deploying-apps/image/overview)'s `CMD`.
* If the service is an [Explicit Service](/docs/how-to-guides/app-guides/define-services#explicit-services-procfiles), then that command is defined by the [Procfile](/docs/how-to-guides/app-guides/define-services).

# Container Environment

Containers run with three types of environment variables and if there is a name collision, [Aptible Metadata](/docs/reference/aptible-metadata-variables) takes precedence over App Configuration, which takes precedence over Docker Image Variables:

## Docker Image Variables

Docker [Images](/docs/core-concepts/apps/deploying-apps/image/overview) define these variables via the `ENV` directive. They are present when your Containers start:

```dockerfile theme={null}
ENV FOO=BAR
```

## App Configuration

Aptible injects an App's [Configuration](/docs/core-concepts/apps/deploying-apps/configuration) as environment variables. For example, for the keys `FOO` and `BAR`:

```shell theme={null}
aptible config:set --app "$APP_HANDLE" \
  FOO=SOME BAR=OTHER
```

Aptible runs containers with the environment variables `FOO` and `BAR` set respectively to `SOME` and `OTHER`.

## Aptible Metadata

Finally, Aptible injects a set of [metadata keys](/docs/reference/aptible-metadata-variables) as environment variables.

These environment variables are accessible through the facilities exposed by the language, such as `ENV` in Ruby, `process.env` in Node, or `os.environ` in Python.

# Container Hostname

Aptible (and Docker in general) sets the hostname for your Containers to the 12 first characters of the Container's ID and uses it in [Logging](/docs/core-concepts/observability/logs/overview) and [Metrics](/docs/core-concepts/observability/metrics/overview).

# Container Isolation

Containers on Aptible are isolated. Use one of the following options to allow multiple Containers to communicate:

* For web APIs or microservices, set up an [Endpoint](/docs/core-concepts/apps/connecting-to-apps/app-endpoints/overview) and direct your requests to the Endpoint.
* For background workers, use a [Database](/docs/core-concepts/managed-databases/overview) as a message queue. Aptible supports [Redis](/docs/core-concepts/managed-databases/supported-databases/redis) and [RabbitMQ](/docs/core-concepts/managed-databases/supported-databases/rabbitmq), which are well-suited for this use case.

# Container Lifecycle

Containers on Aptible are frequently recycled during Operations - meaning new Containers are created during an Operation, and the old ones are terminated. This happens within the following Operations:

* Redeploying an App
* Restarting an App or Database
* Scaling an App or Database

### Graceful termination

Containers are given a grace period after the initial `SIGTERM` to exit before receiving a hard `SIGKILL`. By default this is 10 seconds, but it can be configured via the **stop timeout** setting on the service. See the [Releases](/docs/core-concepts/apps/deploying-apps/releases/overview) page for more information and caveats.

# Filesystem Implications

By default, the filesystem for your [Containers](/docs/core-concepts/architecture/containers/overview) is ephemeral, with the notable exceptions of [Database](/docs/core-concepts/managed-databases/overview) data and any [Persistent Disk](/docs/core-concepts/apps/persistent-disks) attached to an App service. Any data stored on the ephemeral filesystem will be gone every time containers are recycled.

For most workloads, do not use the filesystem to retain long-term data. Instead, store data in a Database or a third-party storage solution, such as AWS S3 (see [How do I accept file uploads when using Aptible?](/docs/how-to-guides/app-guides/use-s3-to-accept-file-uploads) for more information). For workloads that need durable local state and don't fit into a Managed Database, see [Persistent Disks](/docs/core-concepts/apps/persistent-disks).

<DocsTableOfContents />


# Environments
Source: https://www.aptible.com/docs/core-concepts/architecture/environments

Learn about grouping resources with environments

<img alt="" />

## Overview

Environments live within [Stacks](/docs/core-concepts/architecture/stacks) and provide logical isolation of resources. Environments on the same Stack share networks and underlying hosts.

[User Permissions](/docs/core-concepts/security-compliance/access-permissions), [Activity Reports](/docs/core-concepts/architecture/operations#activity-reports), and [Database Backup Retention Policies](/docs/core-concepts/managed-databases/managing-databases/database-backups) are also managed on the Environment level.

<Tip>
  You may want to consider having your production Environments in separate Stacks from staging, testing, and development Environments to ensure network-level isolation.
</Tip>

## FAQ

<AccordionGroup>
  <Accordion title="Is there a limit to how many Environments I can have in a given stack?">
    No, there is no limit to the number of Environments you can have.
  </Accordion>

  <Accordion title="How do I create Environments?">
    ### Read more

    <Card title="How to create environments" icon="book-open-reader" href="/how-to-guides/platform-guides/create-environment" />
  </Accordion>

  <Accordion title="How do I delete Environments?">
    ### Read more

    <Card title="How to delete environments" icon="book-open-reader" href="/how-to-guides/platform-guides/delete-environment" />
  </Accordion>

  <Accordion title="How do I rename Environments?">
    Environments can be renamed from the Aptible Dashboard within the Environment's Settings.
  </Accordion>

  <Accordion title="How do I migrate Environments?">
    ### Read more

    <Card title="How to migrate environments" icon="book-open-reader" href="/how-to-guides/platform-guides/migrate-environments" />
  </Accordion>
</AccordionGroup>


# Maintenance
Source: https://www.aptible.com/docs/core-concepts/architecture/maintenance

Learn about how Aptible simplifies infrastructure maintenance

## Overview

At Aptible, we are committed to providing a managed infrastructure solution that empowers you to focus on your applications while we handle the essential maintenance tasks, ensuring the continued reliability and security of your services.

To this extent, Aptible may schedule maintenance on your resources for several reasons, including but not limited to:

* **EC2 Hardware**: Aptible hardware is hosted on AWS EC2 (See: [Architecture](/docs/core-concepts/architecture/overview)). Hardware can occasionally fail or require replacement. Aptible ensures that these issues are promptly addressed without disrupting your services.
* **Platform Security Upgrades**: Security is a top priority. Aptible handles security upgrades to protect your infrastructure from vulnerabilities and threats.
* **Platform Feature Upgrades**: Aptible continuously improves the platform to provide enhanced features and capabilities. Some upgrades may result in scheduled maintenance on various resources.
* **Database-Specific Security Upgrades**: Critical patches and security updates for supported database types are essential to keep your data secure. Aptible ensures that these updates are applied promptly.

Aptible will notify you of upcoming maintenance ahead of time, including the maintenance window, expectations for automated maintenance, and instructions for self-serve maintenance (if applicable).

## Maintenance Notifications

Our commitment to transparency ensures that you are always aware of scheduled maintenance windows and the reasons behind each maintenance type.

To notify you of upcoming maintenance, we will update our [status page](https://status.aptible.com/) and/or use your Ops Alert contact settings on your organization to notify you, providing you with the information you need to manage your resources effectively.

## Performing Maintenance

Scheduled maintenance can be handled in one of two ways

* **Automated Maintenance:** Aptible will automatically execute maintenance during scheduled windows, eliminating the need for manual intervention. You can trust us to manage these tasks efficiently and be monitored by our SRE team. During this time, Aptible will perform a restart operation on all impacted resources, as identified in the maintenance notifications.
* **Self-Service Maintenance (if applicable):** For maintenance impacting apps and databases, Aptible may provide a self-service option for performing the maintenance yourself. This allows you to perform the maintenance during the best window for you.

## Self-service Maintenance

Aptible may provide instructions for self-service maintenance for apps and databases. When available, you can perform maintenance by restarting the affected app or database before the scheduled window. Many operations, such as deploying an app, scaling a database, or creating a new [Release](/docs/core-concepts/apps/deploying-apps/releases/overview), will also complete scheduled maintenance.

To identify which apps or databases require maintenance and view the scheduled maintenance window for each resource, you can use the following Aptible CLI commands:

* [`aptible maintenance:apps`](/docs/reference/aptible-cli/cli-commands/cli-maintenance-apps)
* [`aptible maintenance:dbs`](/docs/reference/aptible-cli/cli-commands/cli-maintenance-dbs)

<Info>
  Please note that you need at least "read" permissions to see the apps and databases requiring a restart. To ensure you are viewing information for all environments, its best this is reviewed by an Account Owner, Aptible Deploy Owner, or any user with privileges to all environments.
</Info>


# Operations
Source: https://www.aptible.com/docs/core-concepts/architecture/operations

Learn more about operations work on Aptible - with minimal downtime and rollbacks

## Overview

An operation is performed and recorded for all changes made to resources, environments, and stacks. As operations are performed, operation logs are outputted and stored within Aptible. Operations are designed with reliability in mind - with minimal downtime and automatic rollbacks.

## Type of Operations

* `backup`: Creates a [database backup](/docs/core-concepts/managed-databases/managing-databases/database-backups)
* `configure`: Sets the [configuration](/docs/core-concepts/apps/deploying-apps/configuration) for an app
* `copy`: Creates a cross-region copy [database backup](/docs/core-concepts/managed-databases/managing-databases/database-backups#cross-region-copy-backups)
* `deploy`: [Deploys a Docker image](/docs/how-to-guides/app-guides/migrate-dockerfile-to-direct-image-deploy) for an app
* `deprovision`: Stops all running [containers](/docs/core-concepts/architecture/containers/overview) and deletes the resources
* `execute`: Creates an [ephemeral SSH session](/docs/core-concepts/apps/connecting-to-apps/ssh-sessions) for an app
* `logs`: Streams [logs](/docs/core-concepts/observability/logs/overview) to CLI
* `modify`: Modifies a [database](/docs/core-concepts/managed-databases/overview) volume type (gp3, gp2, standard) or provisioned IOPS (if gp3)
* `provision`: Provisions a new [database](/docs/core-concepts/managed-databases/overview), [log drain](/docs/core-concepts/observability/logs/log-drains/overview), or [metric drain](/docs/core-concepts/observability/metrics/metrics-drains/overview)
* `purge`: Deletes a [database backup](/docs/core-concepts/managed-databases/managing-databases/database-backups)
* `rebuild`: Rebuilds the Docker [image](/docs/core-concepts/apps/deploying-apps/image/overview) for an app and deploys the app with the newly built image
* `reload`: Restarts the [database](/docs/core-concepts/managed-databases/overview) in place (does not alter size)
* `replicate`: Creates a [replica](/docs/core-concepts/managed-databases/managing-databases/replication-clustering) for databases that support replication.
* `renew`: Renews a certificate for an [app endpoint using Managed HTTPS](/docs/core-concepts/apps/connecting-to-apps/app-endpoints/https-endpoints/overview).
* `restart`: Restarts an [app](/docs/core-concepts/apps/overview) or [database](/docs/core-concepts/managed-databases/overview)
* `restore`: Restores a [database backup](/docs/core-concepts/managed-databases/managing-databases/database-backups) into a new database
* `scale`: Scales a [service](/docs/core-concepts/apps/deploying-apps/services) for an app

## Operation Logs

For all operations performed, Aptible collects operation logs. These logs are retained only for active resources.

## Minimal downtime operations

To further mitigate the impact of failures, Aptible Operations are designed to be interruptible at any stage whenever possible.

In particular, when deploying a web application, Aptible performs [Zero-Downtime Deployment](/docs/core-concepts/apps/connecting-to-apps/app-endpoints/https-endpoints/overview#zero-downtime-deployment). This ensures that if the Operation is interrupted at any time and for any reason, it still won't take your application down.

When downtime is inevitable (such as when resizing a Database volume or redeploying a Database to a bigger instance), Aptible optimizes for minimal downtime.

For example, when redeploying a Database to another instance, Aptible must perform the following steps:

* Shut down the old Database [Container](/docs/core-concepts/architecture/containers/overview).
* Unmount and then detach the Database volume from the instance the Database was originally scheduled on.
* Attach then remount the Database volume on the instance the Database is being re-scheduled on.
* Start the new Database Container.

When performing this Operation, Aptible will minimize downtime by ensuring that all preconditions are in place to start the new Database Container on the new instance before shutting down the old Database Container. In particular, Aptible will ensure the new instance is available and has pre-pulled the Docker image for your Database.

## Operation Rollbacks

Aptible was designed with reliability in mind. To this extent, Aptible provides automatic rollbacks for failed operations. Users can also manually rollback an operation should they need to.

#### Automatic Rollbacks

All Aptible operations are designed to support automatic rollbacks in the event of a failure (with the exception of a handful of trivial operations with no side effects (such as launching [Ephemeral SSH Sessions](/docs/core-concepts/apps/connecting-to-apps/ssh-sessions)).

When a failure occurs, and an automatic rollback is initiated, a message will be displayed within the operation logs. The logs will indicate whether the rollback succeeded (i.e., everything was restored back to the way it was before the Operation) or failed (some changes could not be undone).

<Warning>
  Some side-effects of deployments cannot be rolled back by Aptible. In particular, database migrations performed in [`before_release`](/docs/core-concepts/apps/deploying-apps/releases/aptible-yml#before-release) commands cannot be rolled back (unless you design your migrations to roll back on failure, of course!). We strongly recommend designing your database migrations so that they are backwards compatible across at least one release. This is a very good idea in general (not just on Aptible), and a best practice for zero-downtime deployments (see [Concurrent Releases](/docs/core-concepts/apps/deploying-apps/releases/overview#concurrent-releases) for more information).
</Warning>

#### Manual Rollbacks

A rollback can be manually initiated within the Aptible CLI by using the [`aptible operation:cancel`](/docs/reference/aptible-cli/cli-commands/cli-operation-cancel) command.

## FAQ

<AccordionGroup>
  <Accordion title="How do I access Operation Logs?">
    Operation Logs can be accessed in the following ways:

    * Within the Aptible Dashboard:
      * Within the resource summary by:
        * Navigating to the respective resource
        * Selecting the Activity tab <img />
      * Within the Activity dashboard by:
        * Navigating to the Activity page
        * Selecting the Logs button for the respective operation
          * Note: This page only shows operations performed in the last 7 days.
    * Within the Aptible CLI by using the [`aptible operation:logs`](/docs/reference/aptible-cli/cli-commands/cli-operation-logs) command
      * Note: This command only shows operations performed in the last 90 days.
  </Accordion>

  <Accordion title="How do I access Activity Reports?">
    Activity Reports can be downloaded in CSV format within the Aptible Dashboard by:

    * Selecting the respective Environment
    * Selecting the **Activity Reports** tab

      <img alt="Activity reports" />
  </Accordion>

  <Accordion title="Why do Operation Failures happen?">
    Reliability is a top priority at Aptible in general and for Aptible in particular. That said, occasional failures during Operations are inevitable and may be caused by the following:

    * Failing third-party services: Aptible strives to minimize dependencies on the critical path to deploying an [App](/docs/core-concepts/apps/overview) or restarting a [Database](/docs/core-concepts/managed-databases/managing-databases/overview), but Aptible nonetheless depends on a number of third-party services. Notably, Aptible depends on AWS EC2, AWS S3, AWS ELB, and the Docker Hub (with a failover or Quay.io and vice-versa). These can occasionally fail and when they do, they may cause Aptible Operations to fail.
    * Crashing instances: Aptible is built on a fleet of Linux instances running Docker. Like any other software, Linux and Docker have bugs and may occasionally crash. Here again, when they do, Aptible operations may fail
  </Accordion>
</AccordionGroup>


# Architecture
Source: https://www.aptible.com/docs/core-concepts/architecture/overview

Learn about the key components of the Aptible platform architecture and how they work together to help you deploy and manage your resources

## Overview

Aptible is an AWS-based container orchestration platform designed for deploying highly available and secure applications and databases to cloud environments. It is compromised of several key components:

* **Stacks:** [Stacks](/docs/core-concepts/architecture/stacks) are fundamental to the network-level isolation of your resources. The underlying virtualized infrastructure (EC2 instances, private network, etc.), provides network-level isolation of resources. Each stack is hosted in a specific region and is comprised of environments. Aptible offers shared stacks (non-isolated) and dedicated stacks (isolated). Dedicated stacks automatically come with a [suite of security features](https://www.aptible.com/secured-by-aptible), including encryption, DDoS protection, host hardening, and [intrusion detection](/docs/core-concepts/security-compliance/hids), alleviating the need to worry about security best practices.
* **Environments:** [Environments](/docs/core-concepts/architecture/environments) determine the logical isolation of your resources. Environments help you maintain a clear separation between development, testing, and production resources, ensuring that changes in one environment do not affect others.
* **Containers:** [Containers](/docs/core-concepts/architecture/containers/overview) are at the heart of how your resources, such as [apps](/docs/core-concepts/apps/overview) and [databases](/docs/core-concepts/managed-databases/overview), are deployed on the Aptible platform. Containers can be easily scaled up or down to meet the needs of your application, making it simple to manage resource allocation.
* **Endpoints (Load Balancers)** allow you to expose your resources to the internet and are responsible for distributing incoming traffic across your containers. They act as load balancers to ensure high availability and reliability for your applications. See [App Endpoints](/docs/core-concepts/apps/connecting-to-apps/app-endpoints/overview) and [Database Endpoints](/docs/core-concepts/managed-databases/connecting-databases/database-endpoints) for more information.

<Tip>
  Need a visual? Check our our [Aptible Architecture Diagram](https://www.aptible.com/assets/deploy-reference-architecture.pdf)
</Tip>

## FAQ

<Accordion title="How does the Aptible platform/architecture compare to Kubernetes?">
  Aptible is a custom-built container orchestration solution designed to streamline deploying, managing, and scaling infrastructure scaling, much like Kubernetes. However, Aptible distinguishes itself by being developed in-house with a strong focus on [security, compliance, and reliability.](/docs/getting-started/introduction) This focus stemmed from our original mission to automate HIPAA compliance. As a result, Aptible has evolved into a platform for engineering teams of all sizes, ensuring private, fully secure, and compliant deployments - without the added complexities of Kubernetes.

  <Note>
    Check out this related blog post "[Kubernetes Challenges: Container Orchestration and Scaling](https://www.aptible.com/blog/kubernetes-challenges-container-orchestration-and-scaling)"
  </Note>

  Moreover, Aptible goes beyond basic orchestration functionalities by providing additional features such as Managed Databases, a 99.95% uptime guarantee, and enterprise-level support for engineering teams of all sizes.
</Accordion>

<Accordion title="What kinds of isolation can Aptible provide?">
  Multitenancy is a key property of most cloud computing service models, which makes isolation a critical component of most cloud computing security models.

  Aptible customers often need to explain to their own customers what kinds of isolation they provide, and what kinds of isolation are possible on the Aptible platform.

  The [Reference Architecture Diagram](https://www.aptible.com/assets/deploy-reference-architecture.pdf) helps illustrate some of the following concepts.

  ### Infrastructure

  All Aptible resources are deployed using Amazon Web Services. AWS operates and secures the physical data centers that produce the underlying compute, storage, and networking functionality needed to run your [Apps](https://www.aptible.com/docs/core-concepts/apps/overview) and [Databases](https://www.aptible.com/docs/core-concepts/managed-databases/overview).

  ### Network/Stack

  Each [Aptible Stack](https://www.aptible.com/docs/core-concepts/architecture/stacks) is an AWS Virtual Private Cloud provisioned with EC2, ELB, and EBS assets and Aptible platform software.

  When you provision a [Dedicated Stack](https://www.aptible.com/docs/core-concepts/architecture/stacks#dedicated-stacks-isolated) on Aptible, you receive your own VPC, meaning you receive your own private and public subnets, isolated from other Aptible customers…

  You can provide further network level isolation between your own Apps and Databases by provisioning Additional Dedicated Stacks.

  ### Host

  The Aptible layers where your Apps and Databases run are backed by AWS EC2 instances, or hosts.

  Each host is deployed in a single VPC. On a Dedicated Stack, this means you are the only Aptible customer using those EC2 virtual servers.

  In a Dedicated Stack, these EC2 instances are AWS Dedicated Instances, meaning Aptible is the sole tenant of the underlying hardware. The AWS hypervisor enforces isolation between EC2 hosts running on the same underlying hardware.

  Within a Stack, the EC2 hosts are organized into Aptible services layers. Each EC2 instance belongs to only one layer, isolating against failures in other layers:

  App Layer: Runs your app containers, terminates SSL. Database Layer: Runs your database containers. Bastion Layer: Provides backend SSH access to your Stack, builds your Docker images. Because Aptible may occasionally need to rotate or deprovision hosts in your Stack to avoid disruptions in service, we do not expose the ability for you to select which specific hosts in your Stack will perform a given workload.

  ### Environment

  [Aptible Environments](https://www.aptible.com/docs/core-concepts/architecture/environments) are used for access control.

  Each environment runs on a specific Stack. Each Stack can support multiple Environments. Note that when you use Environments to separate Apps or Databases, those resources will share networks and underlying hosts if they are on the same Stack.

  You can use separate Environments to isolate access to specific Apps or Databases to specific members of your organization.

  ### Container

  Aptible uses Docker to build and run your App and Database [Containers](https://www.aptible.com/docs/core-concepts/architecture/containers/overview).

  Each container is a lightweight virtual machine that isolates Linux processes running on the same underlying host. Containers are generally isolated from each other, but are the weakest level of isolation.

  You can provide container-level isolation between your own customers by provisioning their resources as separate Apps and Databases.
</Accordion>


# Reliability Division of Responsibilities
Source: https://www.aptible.com/docs/core-concepts/architecture/reliability-division



## Overview

Aptible is a Platform as a Service that simplifies infrastructure management for developers. However, it's important to note that users have certain responsibilities as well.

This document builds on the [Divisions of Responsibility](https://www.aptible.com/assets/deploy-division-of-responsibilities.pdf) between Aptible and users, focusing on use cases related to Reliability and Disaster Recovery. The goal is to provide users with a clear understanding of the monitoring and processes that Aptible manages on their behalf, as well as areas that are not covered.

While this document covers essential aspects, it's important to remember that it doesn't include all responsibilities in detail. Nevertheless, it's a valuable resource to help users navigate their infrastructure responsibilities effectively within the Aptible ecosystem.

## Uptime

Uptime refers to the percentage of time that the Aptible platform is operational and available for use. Aptible provides a 99.95% uptime SLA guarantee for dedicated stacks and on the Enterprise Plan.

Aptible

* Aptible will send notifications of availability incidents for all dedicated environments and corresponding resources, including but not limited to stacks and databases.

  * For service-wide availability incidents, Aptible will notify users of the incident within the Aptible Dashboard and our [Status Page](https://status.aptible.com/). For all other availability incidents on dedicated stacks, Aptible will notify the Ops Alert contact.

* Aptible will issue a credit for SLA breaches as defined by our SLA guarantee for dedicated stacks and organizations on the Enterprise Plan.

Users

* To receive Aptible’s 99.95% uptime SLA, Enterprise users are responsible for ensuring their critical resources, such as production environments, are provisioned on dedicated stacks.

* To receive email notifications of availability incidents impacting the Aptible platform, users are responsible for subscribing to email notifications on our [Status Page](https://status.aptible.com/).

* Users are responsible for providing a valid Ops Alert Contact. Ops Alert Contact should be reachable by [support@aptible.com](mailto:support@aptible.com)

## Maintenance

Maintenance can occur at any time, causing unavailability of Aptible resources (including but not limited to stacks, databases, VPNs, and log drains). Scheduled maintenance typically occurs between 9 pm and 9 am ET on weekdays, or between 6 pm and 10 am ET on weekends. Unscheduled maintenance may occur in situations like critical security patching.

Aptible

* Aptible will notify the Ops Alert contact of scheduled maintenance for dedicated stacks or service-wide with at least two weeks out whenever possible. However, there may be cases where Aptible provides less notice, such as AWS instance retirement, or no prior notice, such as critical security patching.

Users

* Users are responsible for providing a valid Ops Alert Contact.

## Hosts

Aptible

* Aptible is solely responsible for the host and the host's health. If a host becomes unhealthy, impacted containers will be moved to a healthy host. This extends to AWS-scheduled hardware maintenance.

## Databases

Aptible

* While Aptible avoids unnecessary database restarts, Aptible may restart your database at any time for the purposes of security or availability. This may include but is not limited to restarts which:

  * Resolve existing availability issue

  * Avoid an imminent, unavoidable availability issue that would have a greater impact than a restart

  * Resolve critical and/or urgent security incident

* Aptible restarts database containers that have exited (see: [Container Recovery](/docs/core-concepts/architecture/containers/container-recovery)).

* Aptible restarts database containers that have run out of memory (see: [Memory Management](/docs/core-concepts/scaling/memory-limits)).

* Aptible monitors database containers stuck in restart loops and will take action to resolve the root cause of the restart loop.

  * Common cases include the database running out of disk space, memory, or incorrect/invalid settings. The on-call Aptible engineer will contact the Ops Alert contact with information about the root cause and action taken.

* Aptible's SRE team receives a list of databases using more than 98% of disk space roughly once a day. Any action taken is on a "best effort" basis, and at the discretion of the responding SRE. Typically, the responding SRE will scale the database and notify the Ops Alert contact, but depending on usage patterns and growth rates, they may instead contact the Ops Alert contact before taking action.

  * Aptible is considering automating this process as part of our roadmap. With this automation, any Database that exceeds 99% disk utilization will be scaled up, and the Ops Alert contact will be notified.

* Aptible ensures that database replicas are distributed across availability zones.

  * There are times when this may not be possible. For example, when recovering a primary or replica after an outage, the fastest path to recovery may be temporarily running both a primary and replica in the same availability zone. In these cases, the Aptible SRE team is notified and will reach out to schedule a time to migrate the database to a new availability zone.

* Aptible automatically takes backups of databases once a day and monitors for failed backups. Backups are created via point-in-time snapshots of the database's disk. As a result, taking a backup causes no performance degradation. The resulting backup is not stored on the primary volume.

* If enabled as part of the retention policy, Aptible copies database backups to another region as long as another geographically appropriate region is available.

Users

* Users are responsible for monitoring performance, resource consumption, latency, network connectivity, or any other metrics for databases other than the metrics explicitly outlined above.

* Users are responsible for monitoring database replica health or replication lag.

* To achieve cross-region replication, users are responsible for enabling cross-region replication.

## Apps

Aptible

* While Aptible avoids unnecessary restarts, Aptible may restart your app at any time. This may include but is not limited to restarts which:

  * Resolve existing availability issue

  * Avoid an imminent, unavoidable availability issue that would have a greater impact than a restart

  * Resolve critical and/or urgent security incident

* Aptible automatically restarts containers that have exited (see: [Container Recovery](/docs/core-concepts/architecture/containers/container-recovery)).

* Aptible restarts containers that have run out of memory (see: [Memory Management](/docs/core-concepts/scaling/memory-limits)).

* Aptible monitors App host disk utilization. When Apps that are writing to the ephemeral file system cause utilization issues, we may restart the Apps to reset the container filesystem back to a clean state.

Users

* Users are responsible for ensuring your container correctly exits (see: "Cases where Container Recovery will not work" in [Container Recovery](/docs/core-concepts/architecture/containers/container-recovery)). If a container is not correctly designed to exit on failure, Aptible does not restart it and has no monitoring that will catch that failure condition.

* Users are responsible for monitoring app containers stuck in restart loops.

* Aptible does not proactively run your apps in another region, nor do we retain a copy of your code or Docker Images required to fail your Apps over to another region. In the event of a regional outage, users are responsible for coordinating with Aptible to restore apps in a new region.

* Users are responsible for monitoring performance, resource consumption, latency, network connectivity, or any other metrics for apps other than the metrics explicitly outlined above.

## VPNs

Aptible

* Aptible provides connectivity between resource(s) in an Aptible customer's [Dedicated Stack](/docs/core-concepts/architecture/stacks) and resource(s) in a customer-specified peer network. Aptible is responsible for the configuration and setup of the Aptible VPN peer. (See [Site-to-site VPN Tunnels](/docs/core-concepts/integrations/network-integrations#site-to-site-vpn-tunnels))

Users

* Users are responsible for coordinating the configuration of the non-Aptible peer.

* Users are responsible for monitoring the connectivity between resources across the VPN Tunnel (this is the responsibility of the customer and/or their partner network operator).


# Stacks
Source: https://www.aptible.com/docs/core-concepts/architecture/stacks

Learn about using Stacks to deploy resources to various regions

<Frame>
  <img alt="" />
</Frame>

## Overview

Stacks are fundamental to the network-level isolation of your resources. Each Stack is hosted in a specific region and is comprised of [environments](/docs/core-concepts/architecture/environments). Aptible offers two types of Stacks: [Shared Stacks](/docs/core-concepts/architecture/stacks#shared-stacks) (non-isolated) and [Dedicated Stacks](/docs/core-concepts/architecture/stacks#dedicated-stacks) (isolated).

Resources in different Stacks can only connect with each other with a [network integration.](/docs/core-concepts/integrations/network-integrations) For example: Databases and Internal Endpoints deployed in a given Stack are not accessible from Apps deployed in other Stacks.

<Note>
  The underlying virtualized infrastructure (EC2 instances, private network, etc.), which provides network-level isolation of resources.
</Note>

## Shared Stacks (Non-Isolated)

Stacks shared across many customers are called Shared Stacks. Use Shared Stacks for development, testing, and staging [Environments](/docs/core-concepts/architecture/environments).

<Warning>
  You can not host sensitive or regulated data with shared stacks.
</Warning>

## Dedicated Stacks (Isolated)

<Info>
  Dedicated Stacks are only available on [Production and Enterprise plans.](https://www.aptible.com/pricing)
</Info>

Dedicated stacks are built for production [environments](/docs/core-concepts/architecture/environments), are dedicated to a single customer, and provide four significant benefits:

* **Tenancy** - Dedicated stacks are isolated from other Aptible customers, and you can also use multiple Dedicated Stacks to architect the [isolation](/docs/core-concepts/architecture/overview#what-kinds-of-isolation-can-aptible-provide) you require within your organization.
* **Availability** - Aptible's [Service Level Agreement](https://www.aptible.com/legal/service-level-agreement/) applies only to Environments hosted on a Dedicated stack.
* **Regulatory** - Aptible will sign a HIPAA Business Associate Agreement (BAA) to cover information processing in Environments hosted on a Dedicated stack.
* **Connectivity** - [Integrations](/docs/core-concepts/integrations/network-integrations), such as VPN and VPC Peering connections, are available only to Dedicated stacks.
* **Security** - Dedicated stacks automatically come with a [suite of security features](https://www.aptible.com/secured-by-aptible), including encryption, DDoS protection, host hardening, and [intrusion detection](/docs/core-concepts/security-compliance/hids), alleviating the need to worry about security best practices.

## Supported Regions

<Frame>
  <img alt="" />
</Frame>

| Region                                    | Available on Shared Stacks | Available on Dedicated Stacks |
| ----------------------------------------- | -------------------------- | ----------------------------- |
| us-east-1 / US East (N. Virginia)         | ✔️                         | ✔️                            |
| us-east-2 / US East (Ohio)                |                            | ✔️                            |
| us-west-1 / US West (N. California)       | ✔️                         | ✔️                            |
| us-west-2 / US West (Oregon)              |                            | ✔️                            |
| eu-central-1 / Europe (Frankfurt)         | ✔️                         | ✔️                            |
| sa-east-1 / South America (São Paulo)     |                            | ✔️                            |
| eu-west-1 / Europe (Ireland)              |                            | ✔️                            |
| eu-west-2 / Europe (London)               |                            | ✔️                            |
| eu-west-3 / Europe (Paris)                |                            | ✔️                            |
| ca-central-1 / Canada (Central)           | ✔️                         | ✔️                            |
| ap-south-1 / Asia Pacific (Mumbai)        | ✔️                         | ✔️                            |
| ap-southeast-2 / Asia Pacific (Sydney)    | ✔️                         | ✔️                            |
| ap-northeast-1 / Asia Pacific (Tokyo)     |                            | ✔️                            |
| ap-southeast-1 / Asia Pacific (Singapore) |                            | ✔️                            |

<Tip>
  A Stack's Region will affect the latency of customer connections based on proximity. For [VPC Peering](/docs/core-concepts/integrations/network-integrations), deploy the Aptible Stack in the same region as the AWS VPC for both latency and DNS concerns.
</Tip>

## FAQ

<AccordionGroup>
  <Accordion title="How do I create or deprovision a dedicated stack?">
    ### Read the guide

    <Card title="How to create and deprovison dedicated stacks" icon="book-open-reader" href="https://www.aptible.com/docs/create-dedicated-stack" />
  </Accordion>

  <Accordion title="Does Aptible support multi-region setups for business continuity?">
    Yes, this is touched on in our [Business Continuity Guide](https://www.aptible.com/docs/business-continuity). For more information about setup, contact Aptible Support.
  </Accordion>

  <Accordion title="How much do Dedicated Stacks cost?">
    See our pricing page for more information: [https://www.aptible.com/pricing](https://www.aptible.com/pricing)
  </Accordion>

  <Accordion title="Can Dedicated Stacks be renamed?">
    Dedicated Stacks cannot be renamed once created. To update the name of a Dedicated Stack, you create a new Dedicated Stack and migrate your resources to this new Stack. Please note: this does incur downtime.
  </Accordion>

  <Accordion title="Can my resources be migrated from a Shared Stack to a Dedicated Stack">
    Yes, contact Aptible Support to request resources be migrated.
  </Accordion>
</AccordionGroup>


# Billing & Payments
Source: https://www.aptible.com/docs/core-concepts/billing-payments

Learn how manage billing & payments within Aptible

# Overview

To review or modify your billing information, navigate to your account settings within the Aptible Dashboard and select the appropriate option from the Billing section of the navigation.

# Navigating Billing

<Tip>Most billing actions are restricted to *Account Owners*. To grant billing access to non-owners, like Finance team members, add them to the [Billing-Only Role](/docs/core-concepts/security-compliance/access-permissions#billing-only). This role provides access to billing tasks without access to Aptible resources.</Tip>

<Frame>
  <img alt="" />
</Frame>

The following information and settings are available under each section:

* Plans: View and manage your plan.
* Contracts: View a list of your billing contracts, if any.
* Invoices & Projections: View historical invoices and your projected future invoices based on current usage patterns.
* Payment Methods: Add or update a payment method.
* Credits: View credits applied to your account.
* Contacts: Manage billing contacts who receive a copy of your invoices by email.
* Billing Address: Set your billing address.

<Info> Aptible uses billing address information to determine your sales tax withholding per your local (state, county, city) tax rates. </Info>

# FAQ

<AccordionGroup>
  <Accordion title="How do I upgrade my plan?">
    Follow these steps to upgrade your account to the Production plan:

    * In the Aptible Dashboard, select **Settings**
    * Select **Plans**

      <img alt="Viewing your Plan in the Aptible Dashboard" />

    To upgrade to Enterprise, [contact Aptible Support.](https://app.aptible.com/support)
  </Accordion>

  <Accordion title="How to downgrade my plan?">
    Follow these steps to downgrade your account to the Development or Production plan:

    * In the Aptible dashboard, select your name at the top right
    * Select Billing Settings in the dropdown that appears
    * On the left, select Plan
    * Choose the plan you would like to downgrade to

    Please note that your active resources must match the limits of the plan you select for the downgrade to succeed. For example: if you downgrade to a plan that only includes up to 3GB RAM - you must scale your resources below 3GB RAM before you can successfully downgrade.
  </Accordion>

  <Accordion title="What payment methods are supported?">
    * All plans: Credit Card and ACH Debit
    * Enterprise plan: Credit Card, ACH Credit, ACH Debit, Wire, Bill.com, Custom Arrangement
  </Accordion>

  <Accordion title="How do I update my payment method?">
    * Credit Card and ACH Debit: In the Aptible dashboard, select your name at the top right > select Billing Settings in the dropdown that appears > select Payment Methods on the left.

    * Enterprise plan only: ACH Credit, Wire, Bill.com, Custom Arrangement: Please contact [Aptible Support](/docs/how-to-guides/troubleshooting/aptible-support) to make necessary updates.
  </Accordion>

  <Accordion title="What's happens when invoices are unpaid/overdue?">
    Invoices can become overdue for several reasons:

    * A card is expired
    * Payment was declined
    * There is no payment method on file

    Aptible suspends accounts with invoices overdue for more than 14 days. If an invoice is unpaid for over 30 days, Aptible will shut down your account.
  </Accordion>

  <Accordion title="How do I see the costs per service or Environment?">
    [Contact Aptible Support](/docs/how-to-guides/troubleshooting/aptible-support) to request a "Detailed Invoice Breakdown Report."
  </Accordion>

  <Accordion title="Can I pay annually?">
    Yes, we offer volume discounts for paying upfront annually. [Contact Aptible Support](/docs/how-to-guides/troubleshooting/aptible-support) to request volume pricing.
  </Accordion>

  <Accordion title="How do I cancel my Aptible account?">
    Please refer to [Cancel my account](/docs/how-to-guides/platform-guides/cancel-aptible-account) for more information.
  </Accordion>

  <Accordion title="How can I get copies of invoices?">
    Billing contacts receive copies of monthly invoices in their email. Only [Account Owners](/docs/core-concepts/security-compliance/access-permissions#account-owners) can add billing contacts. Add billing contacts using these steps:

    * In the Aptible dashboard, select your name at the top right
    * Select Billing Settings in the dropdown that appears
    * On the left, select Contacts
  </Accordion>
</AccordionGroup>


# Datadog Integration
Source: https://www.aptible.com/docs/core-concepts/integrations/datadog

Learn about using the Datadog Integration for logging and monitoring

# Overview

Aptible integrates with [Datadog](https://www.datadoghq.com/), allowing you to send information about your Aptible resources directly to your Datadog account for monitoring and analysis. You can send the following data directly to your Datadog account:

* **Logs:** Send logs to Datadog’s [log management](https://docs.datadoghq.com/logs/) using a log drains
* **Container Metrics:** Send app and database container metrics to Datadog’s [container monitoring](https://www.datadoghq.com/product/container-monitoring/) using a metric drain
* **In-Process Instrumentation Data (APM):** Send instrumentation data to [Datadog’s APM](https://www.datadoghq.com/product/apm/) by deploying a single Datadog Agent app

> Please note, Datadog's documentation defaults to v2. Please use v1 Datadog documentation with Aptible.

## Datadog Log Integration

On Aptible, you can set up a Datadog [log drain](/docs/core-concepts/observability/logs/log-drains/overview) within an environment to send logs for apps, databases, SSH sessions and endpoints directly to your Datadog account for [log management and analytics](https://www.datadoghq.com/product/log-management/).

<Info> On other platforms, you might configure this by installing the Datadog Agent and setting `DD_LOGS_ENABLED`.</Info>

<Tip>Add tags as query parameters to your Datadog log drain URL to filter logs in Datadog. For example, append `?env=production` to your intake URL to add the `env` tag with value `production`.</Tip>

<Accordion title="Creating a Datadog Log Drain">
  A Datadog Log Drain can be created in three ways on Aptible:

  * Within the Aptible Dashboard by:
    * Navigating to an Environment
    * Selecting the **Log Drains** tab
    * Selecting **Create Log Drain**
    * Selecting **Datadog**
  * Using the [`aptible log_drain:create:datadog`](/docs/reference/aptible-cli/cli-commands/cli-log-drain-create-datadog) CLI command
</Accordion>

## Datadog Container Monitoring Integration

On Aptible, you can set up a Datadog [metric drain](/docs/core-concepts/observability/metrics/metrics-drains/overview) within an environment to send metrics directly to your Datadog account. This enables you to use Datadog’s [container monitoring](https://www.datadoghq.com/product/container-monitoring/) for apps and databases. Please note that not all features of container monitoring are supported (including but not limited to Docker integrations and auto-discovery).

<Info>On other platforms, you might configure this by installing the Datadog Agent and setting `DD_PROCESS_AGENT_ENABLED`.</Info>

<Accordion title="Creating a Datadog Metric Drain">
  A Datadog Log Drain can be created in three ways on Aptible:
  A Datadog Metric Drain can be provisioned in three ways on Aptible:

  * Within the Aptible Dashboard by:
    * Navigating to an Environment:
    * Selecting the **Metric Drains** tab
    * Selecting **Create Metric Drain**
  * Using the [`aptible metric_drain:create:datadog`](/docs/reference/aptible-cli/cli-commands/cli-metric-drain-create-datadog) CLI command
  * Using the Aptible [Terraform Provider](https://registry.terraform.io/providers/aptible/aptible/latest/docs)
</Accordion>

### Datadog Metrics Structure

Aptible metrics are reported as [Custom Metrics](https://docs.datadoghq.com/developers/metrics/custom_metrics/) in Datadog. The following metrics are reported (all these metrics are reported as `gauge` in Datadog, approximately every 30 seconds):

* `enclave.running`: a boolean indicating whether the Container was running when this point was sampled.
* `enclave.milli_cpu_usage`: the Container's average CPU usage (in milli CPUs) over the reporting period.
* `enclave.milli_cpu_limit`: the maximum CPU accessible to the container.
* `enclave.memory_total_mb`: the Container's total memory usage. See [Understanding Memory Utilization](/docs/core-concepts/scaling/memory-limits#understanding-memory-utilization) for more information on memory usage.
* `enclave.memory_rss_mb`: the Container's RSS memory usage. This memory is typically not reclaimable. If this exceeds the `memory_limit_mb`, the container will be restarted.
  <Note> Review [Understanding Memory Utilization](/docs/core-concepts/scaling/memory-limits#understanding-memory-utilization) for more information on the meaning of the `enclave.memory_total_mb` and `enclave.memory_rss_mb` values. </Note>
* `enclave.memory_limit_mb`: the Container's [Memory Limit](/docs/core-concepts/scaling/memory-limits).
* `enclave.disk_read_kbps`: the Container's average disk read bandwidth over the reporting period.
* `enclave.disk_write_kbps`: the Container's average disk write bandwidth over the reporting period.
* `enclave.disk_read_iops`: the Container's average disk read IOPS over the reporting period.
* `enclave.disk_write_iops`: the Container's average disk write IOPS over the reporting period.
  <Note> Review [I/O Performance](/docs/core-concepts/scaling/database-scaling#i-o-performance) for more information on the meaning of the `enclave.disk_read_iops` and `enclave.disk_write_iops` values. </Note>
* `enclave.disk_usage_mb`: the Database's Disk usage (Database metrics only).
* `enclave.disk_limit_mb`: the Database's Disk size (Database metrics only).
* `enclave.pids_current`: the current number of tasks in the Container (see [Other Limits](/docs/core-concepts/security-compliance/ddos-pid-limits)).
* `enclave.pids_limit`: the maximum number of tasks for the Container (see [Other Limits](/docs/core-concepts/security-compliance/ddos-pid-limits)).

All metrics published in Datadog are enriched with the following tags:

* `environment`: Environment handle
* `app`: App handle (App metrics only)
* `database`: Database handle (Database metrics only)
* `service`: Service name
* `container`: Container ID

Finally, Aptible also sets the `host_name` tag on these metrics to the [Container Hostname (Short Container ID).](/docs/core-concepts/architecture/containers/overview#container-hostname)

## Datadog APM

On Aptible, you can configure in-process instrumentation Data (APM) to be sent to [Datadog’s APM](https://www.datadoghq.com/product/apm/) by deploying a single Datadog Agent app and configuring each of your apps to:

* Enable Datadog in-process instrumentation and
* Forward those data through the Datadog Agent app separately hosted on Aptible

<Card title="How to set up Datadog APM" icon="book-open-reader" href="https://www.aptible.com/docs/datadog-apm" />


# Mezmo Integration
Source: https://www.aptible.com/docs/core-concepts/integrations/mezmo

Learn about sending Aptible logs to Mezmo

## Overview

Mezmo, formerly known as LogDNA, is a cloud-based platform for log management and analytics. With Aptible's integration, you can send logs directly to Mezmo for analysis and storage.

## Set up

<Info> Prerequisites: A Mezmo account</Info>

<Steps>
  <Step title="Configure your Mezmo account for Aptible Log Ingestion">
    Refer to the [Mezmo documentation for setting up Aptible Log Ingestion on Mezmo.](https://docs.mezmo.com/docs/aptible-logs)

    Note: Like all Aptible Log Drain providers, Mezmo also offers Business Associate Agreements (BAAs). To ensure HIPAA compliance, please contact them to execute a BAA.
  </Step>

  <Step title="Configure your Log Drain">
    You can send your Aptible logs directly to Mezmo with a [log drain](https://www.aptible.com/docs/log-drains). A Mezmo/LogDNA Log Drain can be created in the following ways on Aptible:

    * Within the Aptible Dashboard by:
      * Navigating to an Environment
      * Selecting the **Log Drains** tab
      * Selecting **Create Log Drain**
      * Selecting **Mezmo**
      * Entering your Mezmo URL
    * Using the [`aptible log_drain:create:logdna`](/docs/reference/aptible-cli/cli-commands/cli-log-drain-create-logdna) command
  </Step>
</Steps>


# Network Integrations: VPC Peering & VPN Tunnels
Source: https://www.aptible.com/docs/core-concepts/integrations/network-integrations



# VPC Peering

<Info> VPC Peering is only available on [Production and Enterprise plans.](https://www.aptible.com/pricing)</Info>

Aptible offers VPC Peering to connect a user’s existing network to their Aptible dedicated VPC. This lets users access internal Aptible resources such as [Internal Endpoints](/docs/core-concepts/apps/connecting-to-apps/app-endpoints/overview) and [Databases](/docs/core-concepts/managed-databases/managing-databases/overview) from their network.

## Access Restrictions and Limitations

VPC peering should be treated as a trusted network connection between the peered VPCs. Aptible does not support custom peer-level rules that restrict a VPC peering connection to specific Aptible resources.

Resources in dedicated Stacks can use dynamic IPs within the Stack CIDR range, which makes resource-specific IP allowlisting impractical at the peering layer. If you need more granular access control than VPC peering provides, contact [Aptible Support](/docs/how-to-guides/troubleshooting/aptible-support) to discuss alternatives.

## Setup

VPC Peering requests can be submitted through the Aptible Dashboard:

<Steps>
  <Step title="Navigate to VPC Peering">
    Go to the Dedicated Stack where you want to create the peering connection and select the **VPC Peering** tab.
  </Step>

  <Step title="Create VPC Peering Request">
    Click **Create VPC Peering Request**. Only Account Owners can create VPC peering requests.
  </Step>

  <Step title="Select Peering Type">
    Choose your peering destination:

    * **Peer to AWS Account**: Connect your Aptible stack to an external AWS VPC you own
    * **Peer to Aptible Dedicated Stack**: Connect two of your Aptible dedicated stacks together
  </Step>
</Steps>

### Peering to an AWS Account

When peering to an external AWS VPC:

1. The Dashboard displays your Aptible VPC information (AWS Account ID, VPC ID, Region, and CIDR) needed to create the peering connection in AWS.
2. Go to the [Peering Connections page](https://console.aws.amazon.com/vpc/home#PeeringConnections) in the AWS VPC Dashboard and click **Create VPC Peering Connection**.
3. Select your own VPC as the local VPC and enter the Aptible VPC details (shown in the Dashboard) for the peer VPC.
4. After creating the peering connection in AWS, copy the **VPC Peering Connection ID** (starts with `pcx-`) and enter it in the Aptible Dashboard form.
5. Submit the request. The Aptible team will accept the peering connection and follow up with next steps.

<Note>
  If you do not see the VPC Peering request flow in the Dashboard, contact [Aptible Support](/docs/how-to-guides/troubleshooting/aptible-support) with the dedicated Stack you want to peer with your AWS VPC.
</Note>

### Peering to Another Aptible Dedicated Stack

When peering two Aptible dedicated stacks together:

1. Select the target dedicated stack from the dropdown.
2. Submit the request. The Aptible team will configure the peering connection between your stacks.

<Note>
  You must have at least two dedicated stacks to use this option.
</Note>

## Managing VPC Peering

The details and status of VPC Peering connections can be viewed within the Aptible Dashboard by:

* Navigating to the respective Dedicated Stack
* Selecting the "VPC Peering" tab

### Requesting Deletion

To request deletion of a VPC peering connection:

1. Navigate to the Dedicated Stack and select the **VPC Peering** tab.
2. Find the peering connection you want to delete and click **Request Deletion**.
3. Confirm by typing the connection ID.
4. Submit the request. The Aptible team will process the deletion.

<Note>
  Only Account Owners can request VPC peering deletion.
</Note>

# VPN Tunnels

<Info> VPN Tunnels are only available on [Production and Enterprise plans.](https://www.aptible.com/pricing) </Info>

Aptible supports site-to-site VPN Tunnels to connect external networks to your Aptible resources. VPN Tunnels are only available on dedicated stacks.

The default protocol for all new VPN Tunnels is IKEv2.

## Setup

VPN Tunnels can only be set up by contacting Aptible Support.

Please provide the following information when you contact [Aptible Support](/docs/how-to-guides/troubleshooting/aptible-support) with your tunnel setup request:

* What resources on the Aptible Stack must be exposed over the tunnel? Aptible can expose:
  * Individual resources. Please share the hostname of the Internal [Endpoints](/docs/core-concepts/apps/connecting-to-apps/app-endpoints/overview) (elb-xxxxx.aptible.in) and the names of the [Databases](/docs/core-concepts/managed-databases/overview) that need to be made accessible over the tunnel.
  * The entire Stack - only recommended if users own the network Aptible is integrating.
  * No resources - or users who need to access resources on the other end of the tunnel without exposing Aptible-side resources.
* Is outbound access from the Stack to the resources exposed on the other end of the tunnel required?

Aptible Support will follow up with a VPN Implementation Worksheet that can be shared with the tunnel partner.

> ❗️Road-warrior VPNs are **not** supported on Aptible. To provide road-warrior users with VPN access to Aptible resources, set up a VPN gateway on a user-owned network and have users connect there, then create a site-to-site VPN tunnel between the user-owned network and the Aptible Dedicated Stack.

## Managing VPN Tunnels

VPN Tunnels can only be managed by the Aptible Support Team. This includes deprovisioning VPN Tunnels.

The details and status of VPN Tunnels can be viewed within the Aptible Dashboard by:

* Navigating to the respective Dedicated Stack
* Selecting the "VPN Tunnels" tab

There are four statuses that you might see in this view:

* `Up`: The connection is fully up
* `Down`: The connection is fully down - consider contacting your partner or Aptible Support
* `Partial`: The connection is in a mixed up/down state, usually because your tunnel is configured as a "connect when there is activity" tunnel, and some connections are not being used
* `Unknown`: Something has gone wrong with the status check; please check again later or reach out to Aptible Support if you are having problems


# All Integrations and Tools
Source: https://www.aptible.com/docs/core-concepts/integrations/overview

Explore all integrations and tools used with Aptible

## Cloud Hosting

Deploy apps and databases to **Aptible's secure cloud** or **integrate with existing cloud** providers to standardize infrastructure.

<CardGroup>
  <Card title="Host in Aptible's cloud">
    <img alt="" />

    <CardGroup>
      <Card title="Get Started→" href="https://app.aptible.com/signup" />

      <Card title="Learn more→" href="https://www.aptible.com/docs/reference/pricing#aptible-hosted-pricing" />
    </CardGroup>
  </Card>

  <Card title="Host in your own AWS">
    <img alt="" />

    <CardGroup>
      <Card title="Request Access→" href="https://app.aptible.com/signup?cta=early-access" />

      <Card title="Learn more→" href="https://www.aptible.com/docs/reference/pricing#self-hosted-pricing" />
    </CardGroup>
  </Card>
</CardGroup>

## Managed Databases

Aptible offers a robust selection of fully [Managed Databases](https://www.aptible.com/docs/databases) that automate provisioning, maintenance, and scaling.

<CardGroup>
  <Card title="Elasticsearch" icon={<svg xmlns="http://www.w3.org/2000/svg" width="30" height="30" viewBox="0 0 48 48"><path fill="#29b6f6" d="M37,24c0-3.314-2.686-6-6-6H5.918C5.323,19.894,5,21.909,5,24s0.323,4.106,0.918,6H31 C34.314,30,37,27.314,37,24z"/><path fill="#4db6ac" d="M25,44c6.524,0,12.305-3.133,15.954-7.968C38.835,34.151,36.055,33,33,33H7.157 C10.453,39.52,17.196,44,25,44z"/><path fill="#ffca28" d="M25,4C17.195,4,10.453,8.48,7.157,15H33c3.051,0,5.828-1.148,7.946-3.024 C37.299,7.138,31.525,4,25,4z"/><path fill="#f9a825" d="M22.073,15c-1.513-3.367-3.845-6.288-6.747-8.501C11.817,8.443,8.957,11.412,7.143,15H22.073z"/><path fill="#009688" d="M15.326,41.501c2.902-2.213,5.233-5.134,6.747-8.501H7.143 C8.957,36.588,11.817,39.557,15.326,41.501z"/><path fill="#212121" d="M5.928,18C5.332,19.895,5,21.907,5,24s0.332,4.105,0.928,6h17.234C23.703,28.092,24,26.081,24,24 s-0.297-4.092-0.837-6H5.928z"/></svg>} href="https://www.aptible.com/docs/elasticsearch" />

  <Card title="InfluxDB" icon={<svg xmlns="http://www.w3.org/2000/svg" width="30" height="30" viewBox="0 0 128 128"><path style={{fillRule:"evenodd",fill:"#020a47",fillOpacity:1}} d="m94.543 87.625 29.379-6.75a3.35 3.35 0 0 0 1.258-.543 3.358 3.358 0 0 0 1.383-2.305c.058-.46.019-.925-.114-1.37L113.957 22.34a3.499 3.499 0 0 0-1.59-2.14 3.49 3.49 0 0 0-2.633-.391l-29.37 6.75c-.887.23-1.65.8-2.118 1.593a3.452 3.452 0 0 0-.383 2.625L90.32 85.094a3.499 3.499 0 0 0 1.59 2.14c.79.477 1.738.618 2.633.391Zm-10.125 33.566 35.621-33.054c1.344-1.36 1.004-2.196-.844-1.528l-24.484 5.575a6.222 6.222 0 0 0-2.715 1.46 6.221 6.221 0 0 0-1.676 2.586l-7.425 23.954c-.508 1.855.168 2.363 1.523 1.007Zm-64.992-10.789 53.344 16.52c.91.172 1.851.012 2.656-.45a3.947 3.947 0 0 0 1.734-2.07l8.938-28.68a3.48 3.48 0 0 0 .117-1.378 3.492 3.492 0 0 0-.418-1.317 3.473 3.473 0 0 0-.89-1.058 3.562 3.562 0 0 0-1.227-.633L30.336 74.973a3.545 3.545 0 0 0-2.695.304 3.57 3.57 0 0 0-1.696 2.118l-8.879 28.62a3.556 3.556 0 0 0 .278 2.68 3.547 3.547 0 0 0 2.082 1.707ZM2.2 51.7l10.816 47.452c.336 1.856 1.207 1.856 1.68 0l7.425-23.949a6.709 6.709 0 0 0 .031-3.113 6.783 6.783 0 0 0-1.37-2.793L3.721 50.852c-1.183-1.395-2.066-1.008-1.523.847ZM43.906.973 3.046 38.875a3.47 3.47 0 0 0-.168 4.848l20.43 22.144a3.483 3.483 0 0 0 2.415 1.098 3.48 3.48 0 0 0 2.484-.926l40.848-37.965a3.446 3.446 0 0 0 .172-4.847L48.832 1.094A3.48 3.48 0 0 0 47.722.3a3.467 3.467 0 0 0-1.326-.3 3.419 3.419 0 0 0-1.34.238 3.435 3.435 0 0 0-1.149.735Zm39.496 85.804c1.864.508 3.035-.496 2.54-2.422L74.124 33.082c-.508-1.855-2.035-2.363-3.375-1.02L32.258 67.895c-1.352 1.343-1.016 2.859.836 3.367Zm20.09-71.515L56.898.972c-1.851-.511-2.187.169-.675 1.684l17.054 18.387a6.549 6.549 0 0 0 2.7 1.527 6.58 6.58 0 0 0 3.093.11l24.485-5.563c1.8-.508 1.8-1.355-.063-1.855Zm0 0"/></svg>} href="https://www.aptible.com/docs/influxdb" />

  <Card title="MySQL" icon="https://www.vectorlogo.zone/logos/mysql/mysql-icon.svg" href="https://www.aptible.com/docs/mysql" />

  <Card title="PostgreSQL" icon={<svg xmlns="http://www.w3.org/2000/svg" width="30" height="30" viewBox="0 0 48 48"><path fill="#fff" d="M44.083,29.79c-0.183-0.829-0.935-1.796-2.452-1.796c-0.31,0-0.649,0.039-1.035,0.119c-0.708,0.146-1.311,0.217-1.842,0.241c4.133-7.04,6.816-16.819,4.159-20.214c-3.501-4.473-8.214-5.141-10.711-5.141L31.967,3c-0.929,0.015-1.893,0.129-2.863,0.339l-3.583,0.774C25.033,4.052,24.536,4.009,24.018,4l-0.03,0l-0.016,0l-0.152-0.001c-1.593,0-3.046,0.338-4.341,0.973l-1.251-0.493c-1.72-0.678-4.308-1.485-6.868-1.485c-0.144,0-0.287,0.003-0.431,0.008C8.407,3.093,6.241,4.05,4.664,5.769C2.696,7.915,1.8,11.054,2.003,15.1C2.013,15.309,4.461,36,11.4,36h0.025l0.064-0.001c0.901-0.022,1.76-0.384,2.563-1.077c0.613,0.46,1.406,0.732,2.145,0.84c0.488,0.115,1.366,0.278,2.418,0.278c1.284,0,2.442-0.263,3.44-0.738c-0.001,0.88-0.006,1.994-0.016,3.418l-0.001,0.075l0.005,0.075c0.097,1.419,0.342,2.698,0.711,3.701c1.051,2.859,2.866,4.434,5.111,4.434c0.093,0,0.188-0.003,0.284-0.009c1.846-0.114,3.717-1.151,5.004-2.772c1.393-1.755,1.715-3.607,1.839-5.026L35,39.111v-0.088v-4.079l0.103,0.01l0.436,0.038l0.042,0.004l0.042,0.002c0.124,0.006,0.252,0.008,0.381,0.008c1.507,0,3.362-0.391,4.616-0.974C41.819,33.476,44.559,31.948,44.083,29.79z"/><path fill="#0277bd" d="M33,34c0-0.205,0.012-0.376,0.018-0.565C33.008,33.184,33,33,33,33s0.012-0.009,0.032-0.022c0.149-2.673,0.886-3.703,1.675-4.29c-0.11-0.153-0.237-0.318-0.356-0.475c-0.333-0.437-0.748-0.979-1.192-1.674l-0.082-0.158c-0.067-0.164-0.229-0.447-0.435-0.819c-1.183-2.14-3.645-6.592-1.96-9.404c0.738-1.232,2.122-1.942,4.121-2.117C33.986,11.718,30.925,6.115,23.985,6c-0.002,0-0.004,0-0.006,0c-6.041-0.098-8.026,5.392-8.672,8.672c0.89-0.377,1.906-0.606,2.836-0.606c0.014,0,0.029,0,0.043,0c2.29,0.017,3.865,1.239,4.323,3.354c0.335,1.552,0.496,2.91,0.492,4.153c-0.01,2.719-0.558,4.149-1.042,5.411l-0.154,0.408c-0.124,0.334-0.255,0.645-0.379,0.937c-0.126,0.298-0.237,0.563-0.318,0.802c0.484,0.11,0.864,0.265,1.125,0.38l0.151,0.066c0.047,0.02,0.094,0.043,0.137,0.069c0.848,0.516,1.376,1.309,1.489,2.233c0.061,0.498,0.051,3.893,0.03,6.855c0.087,1.285,0.305,2.364,0.593,3.146c0.409,1.114,1.431,3.241,3.394,3.119c1.37-0.085,2.687-0.919,3.561-2.019c0.938-1.181,1.284-2.487,1.414-3.958V34z"/><path fill="#0277bd" d="M15.114 28.917c-1.613-1.683-2.399-3.947-2.104-6.056.285-2.035.124-4.027.037-5.098-.029-.357-.048-.623-.047-.77 0-.008.002-.015.003-.023 0-.004-.002-.007-.002-.011.121-3.021 1.286-7.787 4.493-10.62C15.932 5.724 13.388 4.913 11 5 7.258 5.136 3.636 7.724 4 15c.137 2.73 3.222 19.103 7.44 19 .603-.015 1.229-.402 1.872-1.176 1.017-1.223 2.005-2.332 2.708-3.104C15.705 29.481 15.401 29.217 15.114 28.917zM37.023 14.731c.015.154.002.286-.022.408.031.92-.068 1.813-.169 2.677-.074.636-.15 1.293-.171 1.952-.021.645.07 1.282.166 1.956.225 1.578.459 3.359-.765 5.437.225.296.423.571.581.837 4.61-7.475 6.468-16.361 4.695-18.626C38.655 5.944 34.941 4.952 31.999 5c-.921.015-1.758.139-2.473.294C34.602 7.754 36.863 13.026 37.023 14.731zM41 30.071c-2.665.55-3.947.257-4.569-.126-.1.072-.2.133-.293.19-.372.225-.961.583-1.105 2.782.083.016.156.025.246.044L35.714 33c1.32.06 3.049-.31 4.063-.781C41.962 31.205 43.153 29.627 41 30.071zM22.023 32.119c-.037-.298-.198-.539-.492-.732l-.108-.047C21.062 31.181 20.653 31 20 31h-.004c-.127.01-.253.019-.38.019-.052 0-.103-.007-.155-.009-.474.365-1.148.647-2.816.99-2.98.759-1.221 1.655-.078 1.794 1.106.277 3.735.614 5.481-.809C22.043 32.537 22.035 32.229 22.023 32.119z"/><path fill="#0277bd" d="M20.681 18.501c-.292.302-.753.566-1.262.484-.828-.134-1.463-1.133-1.417-1.508h0c.044-.374.751-.569 1.578-.435.287.047.548.128.768.228-.32-.688-.899-1.085-1.782-1.182-1.565-.174-3.226.644-3.56 1.097.007.11.02.251.033.417.093 1.147.265 3.284-.05 5.537-.208 1.485.393 3.169 1.567 4.395.757.79 1.641 1.29 2.513 1.438.111-.478.309-.944.513-1.425.113-.265.233-.547.346-.852l.162-.427c.443-1.155.9-2.35.909-4.703C21.003 20.66 20.892 19.627 20.681 18.501zM34.847 22.007c-.104-.729-.211-1.484-.185-2.303.023-.742.105-1.442.184-2.119.062-.533.11-1.045.138-1.55-1.289.107-2.145.479-2.551 1.108.168-.057.358-.102.568-.129.892-.116 1.543.141 1.618.637.055.363-.253.705-.388.836-.277.269-.626.442-.981.488-.064.008-.129.012-.192.012-.353 0-.69-.121-.949-.3.112 1.973 1.567 4.612 2.283 5.907.153.277.271.498.369.688C35.154 24.163 35.009 23.143 34.847 22.007z"/></svg>} href="https://www.aptible.com/docs/postgresql" />

  <Card title="RabbitMQ" icon="https://www.rabbitmq.com/assets/files/rabbitmq-logo-e91cacd38fcef5219149bc5cfa10b384.svg" href="https://www.aptible.com/docs/rabbitmq" />

  <Card title="Redis" icon={<svg xmlns="http://www.w3.org/2000/svg" width="30" height="30" viewBox="0 0 48 48"><path fill="#b71c1c" d="M45,29.316c0-0.637-1.686-1.153-3.769-1.153c-1.812,0-3.32,0.391-3.683,0.911	c-3.586-1.694-7.173-3.388-10.759-5.083c-1.248-0.59-2.673-0.584-3.918,0.014c-3.818,1.837-7.636,3.674-11.454,5.511	c-0.864-0.126-1.907-0.201-3.032-0.201C5.408,29.316,3,29.832,3,30.469v3.46c0,0.033,0.033,0.064,0.045,0.096	c-0.146,0.555,0.07,1.205,0.649,1.478c5.641,2.665,11.281,5.329,16.922,7.994c1.432,0.677,3.068,0.671,4.496-0.016	c6.442-3.1,12.884-6.199,19.327-9.299c0.484-0.233,0.651-0.786,0.509-1.247C44.971,32.882,45,32.83,45,32.775V29.316z"/><path fill="#e53935" d="M20.616,39.158c-5.641-2.522-11.281-5.044-16.922-7.566c-0.922-0.412-0.926-1.727-0.007-2.146	c6.395-2.912,12.789-5.824,19.184-8.736c1.244-0.567,2.67-0.572,3.918-0.014c5.881,2.63,11.763,5.259,17.644,7.889	c0.754,0.337,0.758,1.414,0.006,1.756c-6.442,2.934-12.884,5.868-19.327,8.801C23.684,39.792,22.048,39.798,20.616,39.158z"/><path fill="#b71c1c" d="M45,21.675c0-0.637-1.686-1.153-3.769-1.153c-1.812,0-3.32,0.391-3.683,0.911	c-3.586-1.694-7.173-3.388-10.759-5.083c-1.248-0.59-2.673-0.584-3.918,0.014c-3.818,1.837-7.636,3.674-11.454,5.511	c-0.864-0.126-1.907-0.201-3.032-0.201C5.408,21.675,3,22.192,3,22.829v3.46c0,0.033,0.033,0.064,0.045,0.096	c-0.146,0.555,0.07,1.205,0.649,1.478c5.641,2.665,11.281,5.329,16.922,7.994c1.432,0.677,3.068,0.671,4.496-0.016	c6.442-3.1,12.884-6.199,19.327-9.299c0.484-0.233,0.651-0.786,0.509-1.247C44.971,25.242,45,25.19,45,25.135V21.675z"/><path fill="#e53935" d="M20.616,31.517c-5.641-2.522-11.281-5.044-16.922-7.566c-0.922-0.412-0.926-1.727-0.007-2.146	c6.395-2.912,12.789-5.824,19.184-8.736c1.244-0.567,2.67-0.572,3.918-0.014c5.881,2.63,11.763,5.259,17.644,7.889	c0.754,0.337,0.758,1.414,0.006,1.756c-6.442,2.934-12.884,5.868-19.327,8.801C23.684,32.152,22.048,32.158,20.616,31.517z"/><path fill="#b71c1c" d="M45,14.035c0-0.637-1.686-1.153-3.769-1.153c-1.812,0-3.32,0.391-3.683,0.911	c-3.586-1.694-7.173-3.388-10.759-5.083c-1.248-0.59-2.673-0.584-3.918,0.014c-3.818,1.837-7.636,3.674-11.454,5.511	c-0.864-0.126-1.907-0.201-3.032-0.201C5.408,14.035,3,14.551,3,15.188v3.46c0,0.033,0.033,0.064,0.045,0.096	c-0.146,0.555,0.07,1.205,0.649,1.478c5.641,2.665,11.281,5.329,16.922,7.994c1.432,0.677,3.068,0.671,4.496-0.016	c6.442-3.1,12.884-6.199,19.327-9.299c0.484-0.233,0.651-0.786,0.509-1.247C44.971,17.601,45,17.549,45,17.494V14.035z"/><path fill="#e53935" d="M20.616,23.877c-5.641-2.522-11.281-5.044-16.922-7.566c-0.922-0.412-0.926-1.727-0.007-2.146	c6.395-2.912,12.789-5.824,19.184-8.736c1.244-0.567,2.67-0.572,3.918-0.014c5.881,2.63,11.763,5.259,17.644,7.889	c0.754,0.337,0.758,1.414,0.006,1.756c-6.442,2.934-12.884,5.868-19.327,8.801C23.684,24.512,22.048,24.517,20.616,23.877z"/><path fill="#fff" d="M18.748,14.741c-0.002,1.042-2.762,2.057-5.093,2.086c-2.419,0.03-5.273-0.993-5.282-2.051	c-0.009-1.061,2.842-2.161,5.311-2.135C16.017,12.665,18.751,13.703,18.748,14.741z"/><path fill="#fff" d="M17.038,18.471c2.393,1.022,4.785,2.045,7.178,3.067c1.054-1.56,2.108-3.12,3.162-4.68	C23.931,17.396,20.485,17.934,17.038,18.471z"/><path fill="#fff" d="M21.86,9.775c-1.101,0.401-2.203,0.801-3.304,1.202c1.507,0.132,3.015,0.264,4.522,0.395	c0.48,0.796,0.959,1.592,1.439,2.387c0.295-0.722,0.59-1.444,0.885-2.166c1.286-0.1,2.572-0.2,3.858-0.3	c-0.997-0.419-1.994-0.839-2.991-1.259c0.254-0.608,0.508-1.216,0.762-1.825c-0.97,0.29-1.939,0.58-2.909,0.87	c-1.07-0.422-2.14-0.843-3.21-1.265C21.228,8.468,21.544,9.122,21.86,9.775z"/><path fill="#b71c1c" d="M27.267,14.619c2.271-0.906,4.543-1.813,6.814-2.719c1.962,0.834,3.924,1.668,5.886,2.502	c-2.202,0.876-4.403,1.752-6.605,2.629C31.331,16.226,29.299,15.423,27.267,14.619z"/><path fill="#a01c1c" d="M34.082,11.963c-0.005,1.596-0.01,3.191-0.015,4.787c1.967-0.783,3.934-1.565,5.901-2.348	C38.006,13.589,36.044,12.776,34.082,11.963z"/></svg>} href="https://www.aptible.com/docs/redis" />

  <Card title="SFTP" icon="file" href="https://www.aptible.com/docs/sftp" />

  <Card title="See all" icon="grid" href="https://www.aptible.com/docs/core-concepts/managed-databases/supported-databases/overview" />
</CardGroup>

## Observability

### Logging

<CardGroup>
  <Card title="Amazon S3" icon="aws" href="https://www.aptible.com/docs/s3-log-archives">
    `Integration` `Limited Release`

    Archive Aptible logs to S3 for historical retention
  </Card>

  <Card
    title="Datadog"
    icon={
<svg fill="#E09600" width="30px" height="30px"  viewBox="0 0 16 16" xmlns="http://www.w3.org/2000/svg" ><path  fill-rule="evenodd" d="M12.886 10.938l-1.157-.767-.965 1.622-1.122-.33-.988 1.517.05.478 5.374-.996-.313-3.378-.879 1.854zm-5.01-1.456l.861-.12c.14.064.237.088.404.13.26.069.562.134 1.009-.092.104-.052.32-.251.408-.365l3.532-.644.36 4.388L8.4 13.876l-.524-4.394zm6.56-1.581l-.348.067-.67-6.964L2.004 2.336l1.407 11.481 1.335-.195a3.03 3.03 0 00-.556-.576c-.393-.33-.254-.888-.022-1.24.307-.596 1.889-1.354 1.8-2.307-.033-.346-.088-.797-.407-1.106-.012.128.01.252.01.252s-.132-.169-.197-.398c-.065-.088-.116-.117-.185-.234-.05.136-.043.294-.043.294s-.107-.255-.125-.47a.752.752 0 00-.08.279s-.139-.403-.107-.62c-.064-.188-.252-.562-.199-1.412.348.245 1.115.187 1.414-.256.1-.147.167-.548-.05-1.337-.139-.506-.483-1.26-.618-1.546l-.016.012c.071.23.217.713.273.947.17.71.215.958.136 1.285-.068.285-.23.471-.642.68-.412.208-.958-.3-.993-.328-.4-.32-.709-.844-.744-1.098-.035-.278.16-.445.258-.672-.14.04-.298.112-.298.112s.188-.195.419-.364c.095-.063.152-.104.252-.188-.146-.003-.264.002-.264.002s.243-.133.496-.23c-.185-.007-.362 0-.362 0s.544-.245.973-.424c.295-.122.583-.086.745.15.212.308.436.476.909.58.29-.13.379-.197.744-.297.321-.355.573-.401.573-.401s-.125.115-.158.297c.182-.145.382-.265.382-.265s-.078.096-.15.249l.017.025c.213-.129.463-.23.463-.23s-.072.091-.156.209c.16-.002.486.006.612.02.745.017.9-.8 1.185-.902.358-.129.518-.206 1.128.396.523.518.932 1.444.73 1.652-.171.172-.507-.068-.879-.534a2.026 2.026 0 01-.415-.911c-.059-.313-.288-.495-.288-.495s.133.297.133.56c0 .142.018.678.246.979-.022.044-.033.217-.058.25-.265-.323-.836-.554-.929-.622.315.26 1.039.856 1.317 1.428.263.54.108 1.035.24 1.164.039.037.566.698.668 1.03.177.58.01 1.188-.222 1.566l-.647.101c-.094-.026-.158-.04-.243-.09.047-.082.14-.29.14-.333l-.036-.065a2.737 2.737 0 01-.819.726c-.367.21-.79.177-1.065.092-.781-.243-1.52-.774-1.698-.914 0 0-.005.112.028.137.197.223.648.628 1.085.91l-.93.102.44 3.444c-.196.029-.226.042-.44.073-.187-.669-.547-1.105-.94-1.36-.347-.223-.825-.274-1.283-.183l-.03.034c.319-.033.695.014 1.08.26.38.24.685.863.797 1.238.144.479.244.991-.144 1.534-.275.386-1.08.6-1.73.138.174.281.409.51.725.554.469.064.914-.018 1.22-.334.262-.27.4-.836.364-1.432l.414-.06.15 1.069 6.852-.83-.56-5.487zm-4.168-2.905c-.02.044-.05.073-.005.216l.003.008.007.019.02.042c.08.168.17.326.32.406.038-.006.078-.01.12-.013a.546.546 0 01.284.047.607.607 0 00.003-.13c-.01-.212.042-.573-.363-.762-.153-.072-.367-.05-.439.04a.175.175 0 01.034.007c.108.038.035.075.015.12zm1.134 1.978c-.053-.03-.301-.018-.475.003-.333.04-.691.155-.77.217-.143.111-.078.305.027.384.297.223.556.372.83.336.168-.022.317-.29.422-.534.072-.167.072-.348-.034-.406zM8.461 5.259c.093-.09-.467-.207-.902.09-.32.221-.33.693-.024.96.03.027.056.046.08.06a2.75 2.75 0 01.809-.24c.065-.072.14-.2.121-.434-.025-.315-.263-.265-.084-.436z" clip-rule="evenodd"/></svg>
}
    href="https://www.aptible.com/docs/datadog"
  >
    `Integration`

    Send Aptible logs to Datadog
  </Card>

  <Card title="Custom - HTTPS" icon="globe" href="https://www.aptible.com/docs/https-log-drains">
    `Custom`

    Send Aptible logs to any destination of your choice via HTTPS
  </Card>

  <Card title="Custom - Syslog" icon="globe" href="https://www.aptible.com/docs/syslog-log-drains">
    `Custom`

    Send Aptible logs to any destination of your choice with Syslog
  </Card>

  <Card title="Elasticsearch" icon={<svg fill="#E09600" width="30px" height="30px" viewBox="0 0 24 24" role="img" xmlns="http://www.w3.org/2000/svg"><path d="M13.394 0C8.683 0 4.609 2.716 2.644 6.667h15.641a4.77 4.77 0 0 0 3.073-1.11c.446-.375.864-.785 1.247-1.243l.001-.002A11.974 11.974 0 0 0 13.394 0zM1.804 8.889a12.009 12.009 0 0 0 0 6.222h14.7a3.111 3.111 0 1 0 0-6.222zm.84 8.444C4.61 21.283 8.684 24 13.395 24c3.701 0 7.011-1.677 9.212-4.312l-.001-.002a9.958 9.958 0 0 0-1.247-1.243 4.77 4.77 0 0 0-3.073-1.11z"/></svg>} href="https://www.aptible.com/docs/elasticsearch-log-drains">
    `Integration`&#x20;

    Send logs to Elasticsearch on Aptible or in the cloud
  </Card>

  <Card title="Logentries" icon={<svg width="30px" height="30px" viewBox="0 0 256 256" version="1.1" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" preserveAspectRatio="xMidYMid"> 	<g> 		<path d="M201.73137,255.654114 L53.5857267,255.654114 C24.0701195,255.654114 0.230590681,231.814585 0.230590681,202.298978 L0.230590681,53.5857267 C0.230590681,24.0701195 24.0701195,0.230590681 53.5857267,0.230590681 L201.73137,0.230590681 C231.246977,0.230590681 255.086506,24.0701195 255.086506,53.5857267 L255.086506,202.298978 C255.086506,231.814585 231.246977,255.654114 201.73137,255.654114 Z" fill="#E09600">  </path> 		<path d="M202.298978,71.7491772 C204.569409,70.0463537 207.407448,68.3435302 209.67788,66.6407067 C208.542664,62.6674519 206.272233,59.261805 204.001801,55.856158 C201.163762,56.9913736 198.893331,58.6941971 196.055292,59.8294128 C194.352468,58.6941971 192.649645,56.9913736 190.379214,55.856158 C190.946821,53.0181188 191.514429,49.6124719 192.082037,46.7744327 C188.108782,45.639217 184.135527,43.9363936 180.162273,43.3687857 C179.027057,46.2068249 178.459449,49.044864 177.324234,51.8829032 C175.053802,51.8829032 172.783371,52.450511 171.080547,53.0181188 C169.377724,50.7476875 167.6749,47.9096484 165.972077,45.639217 C161.998822,46.7744327 158.593175,49.044864 155.187528,51.8829032 C156.322744,54.7209423 157.457959,57.5589815 159.160783,60.3970206 C157.457959,62.0998441 156.322744,63.8026676 155.187528,65.5054911 C152.349489,64.9378832 148.943842,64.3702754 146.105803,63.8026676 C144.970587,67.7759224 143.835372,71.7491772 142.700156,75.722432 C145.538195,76.8576477 148.376234,77.9928633 151.214273,78.5604712 C151.214273,80.8309025 151.781881,83.1013338 151.781881,85.3717651 C149.51145,87.0745886 146.673411,88.7774121 144.402979,90.4802356 C145.538195,94.4534904 147.808626,97.8591374 150.646666,101.264784 C153.484705,100.129569 156.322744,98.4267452 159.160783,97.2915295 C160.863606,98.994353 162.56643,100.129569 164.269253,101.264784 C163.701646,104.102823 163.134038,107.50847 162.56643,110.34651 C166.539685,112.049333 170.51294,112.616941 174.486194,113.184549 C175.053802,110.34651 176.189018,107.50847 177.324234,104.670431 C179.594665,104.670431 181.865096,104.102823 184.135527,104.102823 C185.838351,106.373255 187.541174,109.211294 189.243998,111.481725 C193.217253,109.778902 196.6229,108.076078 199.460939,105.238039 C198.325723,102.4 196.6229,99.5619609 195.487684,96.7239217 C196.6229,95.0210982 198.325723,93.3182747 199.460939,91.6154512 C202.298978,92.1830591 205.704625,92.7506669 208.542664,93.3182747 C209.67788,89.3450199 211.380703,85.3717651 211.948311,81.3985103 C209.110272,80.8309025 206.272233,79.6956868 203.434194,78.5604712 C203.434194,76.2900398 202.866586,74.0196085 202.298978,71.7491772 L202.298978,71.7491772 Z M189.811606,79.6956868 C189.811606,87.0745886 181.865096,92.1830591 175.053802,89.9126277 C168.810116,88.2098043 164.836861,80.8309025 167.107293,74.5872164 C168.242508,70.6139615 171.648155,68.3435302 175.053802,67.2083146 C182.432704,64.9378832 190.379214,71.7491772 189.811606,79.6956868 L189.811606,79.6956868 Z" fill="#FFFFFF">  </path> 		<circle fill="#F36D21" cx="177.324234" cy="78.5604712" r="17.0282349">  </circle> 		<path d="M127.374745,193.217253 C140.997332,192.649645 150.079058,202.298978 160.863606,207.975056 C176.756626,216.489174 192.082037,214.78635 204.001801,200.596155 C209.67788,193.784861 212.515919,186.973567 212.515919,179.594665 L212.515919,179.594665 C212.515919,172.783371 209.67788,165.404469 204.569409,159.160783 C192.649645,144.402979 177.324234,144.402979 161.431214,152.349489 C155.755136,155.187528 150.646666,159.728391 144.402979,162.56643 C129.645176,169.377724 115.45498,168.810116 102.4,156.890352 C89.3450199,144.402979 84.8041573,130.212784 92.7506669,113.752157 C95.588706,108.076078 99.5619609,102.4 102.4,96.7239217 C111.481725,80.2632946 113.184549,63.8026676 97.8591374,50.7476875 C91.6154512,45.0716092 84.2365495,42.8011779 77.4252555,42.8011779 L77.4252555,42.8011779 C70.6139615,42.8011779 63.2350598,45.639217 56.4237658,50.7476875 C40.5307466,63.2350598 38.8279231,80.8309025 49.6124719,96.1563139 C65.5054911,118.293019 67.2083146,138.159293 50.1800797,160.295999 C39.3955309,174.486194 39.3955309,190.946821 53.0181188,204.001801 C59.8294128,210.813095 67.2083146,213.651135 74.5872164,213.651135 L74.5872164,213.651135 C81.9661181,213.651135 89.9126277,210.813095 97.2915295,206.272233 C106.940863,200.028547 115.45498,192.082037 127.374745,193.217253 L127.374745,193.217253 Z" fill="#FFFFFF">  </path> 	</g> </svg>} href="https://www.aptible.com/docs/core-concepts/observability/logs/log-drains/syslog-log-drains#syslog-log-drains">
    `Integration`

    Send Aptible logs to Logentries
  </Card>

  <Card title="Mezmo" icon={<svg version="1.0" xmlns="http://www.w3.org/2000/svg"  width="30" height="30" viewBox="0 0 300.000000 300.000000"  preserveAspectRatio="xMidYMid meet"> <g transform="translate(0.000000,300.000000) scale(0.050000,-0.050000)" fill="#E09600" stroke="none"> <path d="M2330 5119 c-86 -26 -205 -130 -251 -220 -60 -118 -61 -2498 -1 -2615 111 -215 194 -244 701 -244 l421 0 0 227 0 228 -285 3 c-465 4 -434 -73 -435 1088 0 1005 0 1002 119 1064 79 40 1861 45 1939 5 136 -70 132 -41 132 -1051 0 -1107 1 -1104 -264 -1104 -190 -1 -186 5 -186 -242 l0 -218 285 0 c315 1 396 22 499 132 119 127 116 96 116 1414 l0 1207 -55 108 c-41 82 -80 124 -153 169 l-99 60 -1211 3 c-668 2 -1239 -4 -1272 -14z"/> <path d="M1185 3961 c-106 -26 -219 -113 -279 -216 l-56 -95 0 -1240 c0 -1737 -175 -1560 1550 -1560 l1230 0 83 44 c248 133 247 127 247 1530 l0 1189 -55 108 c-112 221 -220 258 -760 259 l-385 0 0 -238 0 -238 285 -8 c469 -13 435 72 435 -1086 0 -1013 1 -1007 -131 -1062 -100 -41 -1798 -41 -1898 0 -132 55 -131 49 -131 1062 0 1115 -15 1061 292 1085 l149 11 -5 232 -6 232 -250 3 c-137 2 -279 -4 -315 -12z"/> </g> </svg>} href="https://www.aptible.com/docs/mezmo">
    `Integration`

    Send Aptible logs to Mezmo (Formerly LogDNA)
  </Card>

  <Card title="Logstash" icon={<svg xmlns="http://www.w3.org/2000/svg" width="30" height="30" viewBox="200 50 200 200" fill="none">   <g clip-path="url(https://mintlify.s3.us-west-1.amazonaws.com/aptible/core-concepts/integrations#clip0_404_1629)">     <path d="M0 8C0 3.58172 3.58172 0 8 0H512C516.418 0 520 3.58172 520 8V332C520 336.418 516.418 340 512 340H8C3.58172 340 0 336.418 0 332V8Z" fill="none"></path>     <path d="M262.969 175.509H195.742V98H216.042C242.142 98 262.969 119.091 262.969 144.927V175.509Z" fill="#E09600"></path>     <path d="M262.969 243C225.797 243 195.478 212.945 195.478 175.509H262.969V243Z" fill="#E09600"></path>     <path d="M262.969 175.509H324.397V243H262.969V175.509Z" fill="#E09600"></path>     <path d="M262.969 175.509H277.206V243H262.969V175.509Z" fill="#E09600"></path>   </g>   <defs>     <clipPath id="clip0_404_1629">       <rect width="520" height="340" fill="white"></rect>     </clipPath>   </defs> </svg>} href="https://www.aptible.com/docs/how-to-guides/observability-guides/https-log-drain#how-to-set-up-a-self-hosted-https-log-drain">
    `Compatible`

    Send Aptible logs to Logstash
  </Card>

  <Card title="Papertrail" icon={<svg fill="#E09600" width="30px" height="30px"  viewBox="-2.5 0 75 75" xmlns="http://www.w3.org/2000/svg" ><path  fill-rule="evenodd"  d="M30.47 30.408l-8.773 2.34C15.668 27.308 8.075 23.9 0 23.04A70.43 70.43 0 0 1 40.898 9.803l-5.026 4.62s21.385-.75 26.755-8.117c-.14.763-.37 1.507-.687 2.217a24.04 24.04 0 0 1-7.774 10.989 44.55 44.55 0 0 1-11.083 6.244 106.49 106.49 0 0 1-12.051 4.402h-.562M64 29.44a117.73 117.73 0 0 0-40.242 5.339 38.71 38.71 0 0 1 6.775 9.647C41.366 38.43 56.258 30.75 63.97 29.7M32 47.485c1.277 3.275 2.096 6.7 2.435 10.21L53.167 38.37z" clip-rule="evenodd"/></svg>} href="https://www.aptible.com/docs/papertrail">
    `Integration`

    Send Aptible logs to Papertrail
  </Card>

  <Card title="Sumo Logic" icon={<svg version="1.0" xmlns="http://www.w3.org/2000/svg"  width="30" height="30" viewBox="0 0 200.000000 200.000000"  preserveAspectRatio="xMidYMid meet"> <metadata> Created by potrace 1.10, written by Peter Selinger 2001-2011 </metadata> <g transform="translate(0.000000,200.000000) scale(0.100000,-0.100000)" fill="#E09600" stroke="none"> <path d="M105 1888 c-3 -7 -4 -411 -3 -898 l3 -885 895 0 895 0 0 895 0 895 -893 3 c-709 2 -894 0 -897 -10z m663 -447 c48 -24 52 -38 19 -69 l-23 -22 -39 20 c-46 23 -93 26 -120 6 -27 -20 -12 -43 37 -56 98 -24 119 -32 148 -56 61 -52 29 -156 -57 -185 -57 -18 -156 -6 -203 25 -46 30 -49 44 -16 75 l23 22 38 -25 c45 -31 124 -36 146 -10 22 27 -2 46 -89 69 -107 28 -122 42 -122 115 0 63 10 78 70 105 46 20 133 14 188 -14z m502 -116 c0 -124 2 -137 21 -156 16 -16 29 -20 53 -15 58 11 66 33 66 178 l0 129 48 -3 47 -3 3 -187 2 -188 -45 0 c-33 0 -45 4 -45 15 0 12 -6 11 -32 -5 -37 -23 -112 -27 -152 -8 -52 23 -61 51 -64 206 -2 78 -1 149 2 157 4 10 20 15 51 15 l45 0 0 -135z m-494 -419 l28 -23 35 24 c30 21 45 24 90 20 46 -3 59 -9 83 -36 l28 -31 0 -160 0 -160 -44 0 -44 0 -4 141 c-3 125 -5 142 -22 155 -29 20 -54 17 -81 -11 -24 -23 -25 -29 -25 -155 l0 -130 -45 0 -45 0 0 119 c0 117 -9 168 -33 183 -22 14 -48 8 -72 -17 -24 -23 -25 -29 -25 -155 l0 -130 -45 0 -45 0 0 190 0 190 45 0 c34 0 45 -4 45 -16 0 -13 5 -12 26 5 38 30 114 29 150 -3z m654 2 c71 -36 90 -74 90 -177 0 -75 -3 -91 -24 -122 -64 -94 -217 -103 -298 -18 l-38 40 0 99 c0 97 1 100 32 135 17 20 45 42 62 50 49 21 125 18 176 -7z"/> <path d="M1281 824 c-28 -24 -31 -31 -31 -88 0 -95 44 -139 117 -115 46 15 66 57 61 127 -4 45 -10 60 -32 79 -36 30 -77 29 -115 -3z"/> </g> </svg>} href="https://www.aptible.com/docs/sumo-logic">
    `Integration`

    Send Aptible logs to Sumo Logic
  </Card>
</CardGroup>

### Metrics and Data

<CardGroup>
  <Card title="Datadog - Container Monitoring" icon={<svg fill="#E09600" width="30px" height="30px"  viewBox="0 0 16 16" xmlns="http://www.w3.org/2000/svg" ><path  fill-rule="evenodd" d="M12.886 10.938l-1.157-.767-.965 1.622-1.122-.33-.988 1.517.05.478 5.374-.996-.313-3.378-.879 1.854zm-5.01-1.456l.861-.12c.14.064.237.088.404.13.26.069.562.134 1.009-.092.104-.052.32-.251.408-.365l3.532-.644.36 4.388L8.4 13.876l-.524-4.394zm6.56-1.581l-.348.067-.67-6.964L2.004 2.336l1.407 11.481 1.335-.195a3.03 3.03 0 00-.556-.576c-.393-.33-.254-.888-.022-1.24.307-.596 1.889-1.354 1.8-2.307-.033-.346-.088-.797-.407-1.106-.012.128.01.252.01.252s-.132-.169-.197-.398c-.065-.088-.116-.117-.185-.234-.05.136-.043.294-.043.294s-.107-.255-.125-.47a.752.752 0 00-.08.279s-.139-.403-.107-.62c-.064-.188-.252-.562-.199-1.412.348.245 1.115.187 1.414-.256.1-.147.167-.548-.05-1.337-.139-.506-.483-1.26-.618-1.546l-.016.012c.071.23.217.713.273.947.17.71.215.958.136 1.285-.068.285-.23.471-.642.68-.412.208-.958-.3-.993-.328-.4-.32-.709-.844-.744-1.098-.035-.278.16-.445.258-.672-.14.04-.298.112-.298.112s.188-.195.419-.364c.095-.063.152-.104.252-.188-.146-.003-.264.002-.264.002s.243-.133.496-.23c-.185-.007-.362 0-.362 0s.544-.245.973-.424c.295-.122.583-.086.745.15.212.308.436.476.909.58.29-.13.379-.197.744-.297.321-.355.573-.401.573-.401s-.125.115-.158.297c.182-.145.382-.265.382-.265s-.078.096-.15.249l.017.025c.213-.129.463-.23.463-.23s-.072.091-.156.209c.16-.002.486.006.612.02.745.017.9-.8 1.185-.902.358-.129.518-.206 1.128.396.523.518.932 1.444.73 1.652-.171.172-.507-.068-.879-.534a2.026 2.026 0 01-.415-.911c-.059-.313-.288-.495-.288-.495s.133.297.133.56c0 .142.018.678.246.979-.022.044-.033.217-.058.25-.265-.323-.836-.554-.929-.622.315.26 1.039.856 1.317 1.428.263.54.108 1.035.24 1.164.039.037.566.698.668 1.03.177.58.01 1.188-.222 1.566l-.647.101c-.094-.026-.158-.04-.243-.09.047-.082.14-.29.14-.333l-.036-.065a2.737 2.737 0 01-.819.726c-.367.21-.79.177-1.065.092-.781-.243-1.52-.774-1.698-.914 0 0-.005.112.028.137.197.223.648.628 1.085.91l-.93.102.44 3.444c-.196.029-.226.042-.44.073-.187-.669-.547-1.105-.94-1.36-.347-.223-.825-.274-1.283-.183l-.03.034c.319-.033.695.014 1.08.26.38.24.685.863.797 1.238.144.479.244.991-.144 1.534-.275.386-1.08.6-1.73.138.174.281.409.51.725.554.469.064.914-.018 1.22-.334.262-.27.4-.836.364-1.432l.414-.06.15 1.069 6.852-.83-.56-5.487zm-4.168-2.905c-.02.044-.05.073-.005.216l.003.008.007.019.02.042c.08.168.17.326.32.406.038-.006.078-.01.12-.013a.546.546 0 01.284.047.607.607 0 00.003-.13c-.01-.212.042-.573-.363-.762-.153-.072-.367-.05-.439.04a.175.175 0 01.034.007c.108.038.035.075.015.12zm1.134 1.978c-.053-.03-.301-.018-.475.003-.333.04-.691.155-.77.217-.143.111-.078.305.027.384.297.223.556.372.83.336.168-.022.317-.29.422-.534.072-.167.072-.348-.034-.406zM8.461 5.259c.093-.09-.467-.207-.902.09-.32.221-.33.693-.024.96.03.027.056.046.08.06a2.75 2.75 0 01.809-.24c.065-.072.14-.2.121-.434-.025-.315-.263-.265-.084-.436z" clip-rule="evenodd"/></svg>} href="https://www.aptible.com/docs/datadog">
    `Integration`

    Send Aptible container metrics to Datadog
  </Card>

  <Card
    title="Datadog - APM"
    icon={
<svg fill="#E09600" width="30px" height="30px"  viewBox="0 0 16 16" xmlns="http://www.w3.org/2000/svg" ><path  fill-rule="evenodd" d="M12.886 10.938l-1.157-.767-.965 1.622-1.122-.33-.988 1.517.05.478 5.374-.996-.313-3.378-.879 1.854zm-5.01-1.456l.861-.12c.14.064.237.088.404.13.26.069.562.134 1.009-.092.104-.052.32-.251.408-.365l3.532-.644.36 4.388L8.4 13.876l-.524-4.394zm6.56-1.581l-.348.067-.67-6.964L2.004 2.336l1.407 11.481 1.335-.195a3.03 3.03 0 00-.556-.576c-.393-.33-.254-.888-.022-1.24.307-.596 1.889-1.354 1.8-2.307-.033-.346-.088-.797-.407-1.106-.012.128.01.252.01.252s-.132-.169-.197-.398c-.065-.088-.116-.117-.185-.234-.05.136-.043.294-.043.294s-.107-.255-.125-.47a.752.752 0 00-.08.279s-.139-.403-.107-.62c-.064-.188-.252-.562-.199-1.412.348.245 1.115.187 1.414-.256.1-.147.167-.548-.05-1.337-.139-.506-.483-1.26-.618-1.546l-.016.012c.071.23.217.713.273.947.17.71.215.958.136 1.285-.068.285-.23.471-.642.68-.412.208-.958-.3-.993-.328-.4-.32-.709-.844-.744-1.098-.035-.278.16-.445.258-.672-.14.04-.298.112-.298.112s.188-.195.419-.364c.095-.063.152-.104.252-.188-.146-.003-.264.002-.264.002s.243-.133.496-.23c-.185-.007-.362 0-.362 0s.544-.245.973-.424c.295-.122.583-.086.745.15.212.308.436.476.909.58.29-.13.379-.197.744-.297.321-.355.573-.401.573-.401s-.125.115-.158.297c.182-.145.382-.265.382-.265s-.078.096-.15.249l.017.025c.213-.129.463-.23.463-.23s-.072.091-.156.209c.16-.002.486.006.612.02.745.017.9-.8 1.185-.902.358-.129.518-.206 1.128.396.523.518.932 1.444.73 1.652-.171.172-.507-.068-.879-.534a2.026 2.026 0 01-.415-.911c-.059-.313-.288-.495-.288-.495s.133.297.133.56c0 .142.018.678.246.979-.022.044-.033.217-.058.25-.265-.323-.836-.554-.929-.622.315.26 1.039.856 1.317 1.428.263.54.108 1.035.24 1.164.039.037.566.698.668 1.03.177.58.01 1.188-.222 1.566l-.647.101c-.094-.026-.158-.04-.243-.09.047-.082.14-.29.14-.333l-.036-.065a2.737 2.737 0 01-.819.726c-.367.21-.79.177-1.065.092-.781-.243-1.52-.774-1.698-.914 0 0-.005.112.028.137.197.223.648.628 1.085.91l-.93.102.44 3.444c-.196.029-.226.042-.44.073-.187-.669-.547-1.105-.94-1.36-.347-.223-.825-.274-1.283-.183l-.03.034c.319-.033.695.014 1.08.26.38.24.685.863.797 1.238.144.479.244.991-.144 1.534-.275.386-1.08.6-1.73.138.174.281.409.51.725.554.469.064.914-.018 1.22-.334.262-.27.4-.836.364-1.432l.414-.06.15 1.069 6.852-.83-.56-5.487zm-4.168-2.905c-.02.044-.05.073-.005.216l.003.008.007.019.02.042c.08.168.17.326.32.406.038-.006.078-.01.12-.013a.546.546 0 01.284.047.607.607 0 00.003-.13c-.01-.212.042-.573-.363-.762-.153-.072-.367-.05-.439.04a.175.175 0 01.034.007c.108.038.035.075.015.12zm1.134 1.978c-.053-.03-.301-.018-.475.003-.333.04-.691.155-.77.217-.143.111-.078.305.027.384.297.223.556.372.83.336.168-.022.317-.29.422-.534.072-.167.072-.348-.034-.406zM8.461 5.259c.093-.09-.467-.207-.902.09-.32.221-.33.693-.024.96.03.027.056.046.08.06a2.75 2.75 0 01.809-.24c.065-.072.14-.2.121-.434-.025-.315-.263-.265-.084-.436z" clip-rule="evenodd"/></svg>
}
    href="https://www.aptible.com/docs/datadog"
  >
    `Compatible`

    Send Aptible application performance metrics to Datadog
  </Card>

  <Card title="Fivetran" icon={<svg fill="#E09600" width="30px" height="30px" viewBox="0 0 100 100" role="img" xmlns="http://www.w3.org/2000/svg"><path  d="M40.8,32h6.4c0.5,0,1-0.4,1-1c0-0.1,0-0.3-0.1-0.4L37.1,0.6C36.9,0.3,36.6,0,36.2,0h-6.4c-0.5,0-1,0.4-1,1 		c0,0.1,0,0.2,0.1,0.3l11.1,30.2C40.1,31.8,40.4,32,40.8,32z"/> 	<path class="st0" d="M39.7,64h6.4c0.5,0,1-0.4,1-1c0-0.1,0-0.2-0.1-0.3L24.2,0.6C24.1,0.3,23.7,0,23.3,0h-6.4c-0.5,0-1,0.4-1,1 		c0,0.1,0,0.2,0.1,0.3l22.8,62.1C38.9,63.8,39.3,64,39.7,64z"/> 	<path class="st0" d="M27,64h6.4c0.5,0,0.9-0.4,1-0.9c0-0.1,0-0.3-0.1-0.4L23.2,32.6c-0.1-0.4-0.5-0.6-0.9-0.6h-6.5 		c-0.5,0-0.9,0.5-0.9,1c0,0.1,0,0.2,0.1,0.3l11,30.1C26.3,63.8,26.6,64,27,64z"/> 	<path class="st0" d="M41.6,1.3l5.2,14.1c0.1,0.4,0.5,0.6,0.9,0.6H54c0.5,0,1-0.4,1-1c0-0.1,0-0.2-0.1-0.3L49.7,0.6 		C49.6,0.3,49.3,0,48.9,0h-6.4c-0.5,0-1,0.4-1,1C41.5,1.1,41.5,1.2,41.6,1.3z"/> 	<path class="st0" d="M15.2,64h6.4c0.5,0,1-0.4,1-1c0-0.1,0-0.2-0.1-0.3l-5.2-14.1c-0.1-0.4-0.5-0.6-0.9-0.6H10c-0.5,0-1,0.4-1,1 		c0,0.1,0,0.2,0.1,0.3l5.2,14.1C14.4,63.8,14.8,64,15.2,64z"/> </svg>                             } href="https://www.aptible.com/docs/connect-to-fivetran">
    `Compatible`

    Send Aptible database logs to Fivetran
  </Card>

  <Card title="InfluxDB" icon={<svg fill="#E09600" width="30px" height="30px" viewBox="-2.5 0 261 261" version="1.1" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" preserveAspectRatio="xMidYMid">     <g>         <path d="M255.59672,156.506259 L230.750771,48.7630778 C229.35754,42.9579495 224.016822,36.920616 217.979489,35.2951801 L104.895589,0.464410265 C103.502359,-2.84217094e-14 101.876923,-2.84217094e-14 100.019282,-2.84217094e-14 C95.1429738,-2.84217094e-14 90.266666,1.85764106 86.783589,4.87630778 L5.74399781,80.3429758 C1.33210029,84.290463 -0.989951029,92.1854375 0.403279765,97.7583607 L26.8746649,213.164312 C28.2678956,218.96944 33.6086137,225.006773 39.6459471,226.632209 L145.531487,259.605338 C146.924718,260.069748 148.550154,260.069748 150.407795,260.069748 C155.284103,260.069748 160.160411,258.212107 163.643488,255.19344 L250.256002,174.61826 C254.6679,169.974157 256.989951,162.543593 255.59672,156.506259 Z M116.738051,26.0069748 L194.52677,49.9241035 C197.545437,50.852924 197.545437,52.2461548 194.52677,52.9427702 L153.658667,62.2309755 C150.64,63.159796 146.228103,61.7665652 144.138257,59.4445139 L115.809231,28.7934364 C113.254974,26.23918 113.719384,25.0781543 116.738051,26.0069748 Z M165.268924,165.330054 C166.197744,168.348721 164.107898,170.206362 161.089231,169.277541 L77.2631786,143.270567 C74.2445119,142.341746 73.5478965,139.78749 75.8699478,137.697643 L139.958564,78.0209245 C142.280616,75.6988732 144.834872,76.6276937 145.531487,79.6463604 L165.268924,165.330054 Z M27.10687,89.398976 L95.1429738,26.0069748 C97.4650251,23.6849235 100.948102,24.1493338 103.270153,26.23918 L137.404308,63.159796 C139.726359,65.4818473 139.261949,68.9649243 137.172103,71.2869756 L69.1359989,134.678977 C66.8139476,137.001028 63.3308706,136.536618 61.0088193,134.446772 L26.8746649,97.5261556 C24.5526135,94.9718991 24.7848187,91.256617 27.10687,89.398976 Z M43.5934344,189.711593 L25.7136392,110.761848 C24.7848187,107.743181 26.1780495,107.046566 28.2678956,109.368617 L56.5969218,140.019695 C58.9189731,142.341746 59.6155885,146.753644 58.9189731,149.77231 L46.6121011,189.711593 C45.6832806,192.962465 44.2900498,192.962465 43.5934344,189.711593 Z M143.209436,236.15262 L54.2748705,208.520209 C51.2562038,207.591388 49.3985627,204.340516 50.3273832,201.089645 L65.1885117,153.255387 C66.1173322,150.236721 69.3682041,148.37908 72.6190759,149.3079 L161.553642,176.708106 C164.572308,177.636926 166.429949,180.887798 165.501129,184.13867 L150.64,231.972927 C149.478975,234.991594 146.460308,236.849235 143.209436,236.15262 Z M222.159181,171.367388 L162.714667,226.632209 C160.392616,228.954261 159.23159,228.02544 160.160411,225.006773 L172.467283,185.06749 C173.396103,182.048824 176.646975,178.797952 179.897847,178.333542 L220.76595,169.045336 C223.784617,167.884311 224.249027,169.277541 222.159181,171.367388 Z M228.660925,159.292721 L179.665642,170.438567 C176.646975,171.367388 173.396103,169.277541 172.699488,166.258875 L151.801026,75.6988732 C150.872206,72.6802064 152.962052,69.4293346 155.980718,68.7327192 L204.976001,57.5868728 C207.994668,56.6580523 211.24554,58.7478985 211.942155,61.7665652 L232.840617,152.326567 C233.537233,155.809644 231.679592,158.828311 228.660925,159.292721 Z">  </path>     </g> </svg>} href="https://www.aptible.com/docs/core-concepts/observability/metrics/metrics-drains/influxdb-metric-drain">
    `Integration`

    Send Aptible container metrics to an InfluxDB
  </Card>

  <Card title="New Relic" icon={<svg viewBox="0 0 832.8 959.8" xmlns="http://www.w3.org/2000/svg" width="30" height="30"><path d="M672.6 332.3l160.2-92.4v480L416.4 959.8V775.2l256.2-147.6z" fill="E09600"/><path d="M416.4 184.6L160.2 332.3 0 239.9 416.4 0l416.4 239.9-160.2 92.4z" fill="E09600"/><path d="M256.2 572.3L0 424.6V239.9l416.4 240v479.9l-160.2-92.2z" fill="#E09600"/></svg>} href="https://github.com/aptible/newrelic-metrics-example">
    `Compatible`

    > Collect custom database metrics for Aptible databases using the New Relic Agent
  </Card>
</CardGroup>

## Developer Tools

<CardGroup>
  <Card title="Aptible CLI" icon={<svg version="1.0" xmlns="http://www.w3.org/2000/svg"  width="30" height="30" viewBox="50 50 200 200"  preserveAspectRatio="xMidYMid meet"> <g transform="translate(0.000000,300.000000) scale(0.100000,-0.100000)" fill="#E09600" stroke="none"> <path d="M873 1982 l-263 -266 0 -173 c0 -95 3 -173 7 -173 5 0 205 197 445 437 l438 438 438 -438 c240 -240 440 -437 445 -437 4 0 7 79 7 176 l0 176 -266 264 -266 264 -361 -1 -362 0 -262 -267z"/> <path d="M1006 1494 l-396 -396 0 -174 c0 -96 3 -174 7 -174 5 0 124 116 265 257 l258 258 0 -258 0 -257 140 0 140 0 0 570 c0 314 -4 570 -9 570 -4 0 -187 -178 -405 -396z"/> <path d="M1590 1320 l0 -570 135 0 135 0 0 260 0 260 260 -260 c143 -143 262 -260 265 -260 3 0 5 80 5 178 l0 177 -394 393 c-217 215 -397 392 -400 392 -3 0 -6 -256 -6 -570z"/> </g> </svg>} href="https://www.aptible.com/docs/reference/aptible-cli/overview">
    `Native`

    Manage your Aptible resources via the Aptible CLI
  </Card>

  <Card title="Custom CI/CD" icon="globe" href="https://www.aptible.com/docs/how-to-guides/app-guides/integrate-aptible-with-ci/overview">
    `Custom`

    Deploy to Aptible using a CI/CD tool of your choice
  </Card>

  <Card title="Circle CI" icon={<svg width="30px" height="30px" viewBox="-1.5 0 259 259" version="1.1" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" preserveAspectRatio="xMidYMid"> 	<g fill="#E09600"> 		<circle cx="126.157031" cy="129.007874" r="30.5932958">  </circle> 		<path d="M1.20368953,96.5716086 C1.20368953,96.9402024 0.835095614,97.6773903 0.835095614,98.0459843 C0.835095614,101.36333 3.41525309,104.312081 7.10119236,104.312081 L59.0729359,104.312081 C61.6530934,104.312081 63.496063,102.837706 64.6018448,100.626142 C75.2910686,77.0361305 98.8810798,61.1865916 125.788436,61.1865916 C163.016423,61.1865916 193.241125,91.4112936 193.241125,128.63928 C193.241125,165.867267 163.016423,196.091969 125.788436,196.091969 C98.5124859,196.091969 75.2910686,179.873835 64.6018448,157.021013 C63.496063,154.440855 61.6530934,152.96648 59.0729359,152.96648 L7.10119236,152.96648 C3.78384701,152.96648 0.835095614,155.546637 0.835095614,159.232575 C0.835095614,159.60117 0.835095614,160.338357 1.20368953,160.706952 C15.5788527,216.733228 66.0762205,258.015748 126.157031,258.015748 C197.295658,258.015748 255.164905,200.146502 255.164905,129.007874 C255.164905,57.8692464 197.295658,0 126.157031,0 C66.0762205,0 15.5788527,41.2825197 1.20368953,96.5716086 L1.20368953,96.5716086 Z">  </path> 	</g> </svg>} href="https://www.aptible.com/docs/how-to-guides/app-guides/integrate-aptible-with-ci/circle-cl#circle-ci">
    `Integration`

    Deploy to Aptible using Circle CI.
  </Card>

  <Card title="GitHub Actions" icon="github" href="https://github.com/marketplace/actions/deploy-to-aptible">
    `Integration`

    Deploy to Aptible using GitHub Actions.
  </Card>

  <Card title="Terraform" icon={<svg fill="#E09600" width="30px" height="30px"  viewBox="0 0 16 16" xmlns="http://www.w3.org/2000/svg" fill="none">  <g fill="#E09600">  <path d="M1 0v5.05l4.349 2.527V2.526L1 0zM10.175 5.344l-4.35-2.525v5.05l4.35 2.527V5.344zM10.651 10.396V5.344L15 2.819v5.05l-4.349 2.527zM10.174 16l-4.349-2.526v-5.05l4.349 2.525V16z"/>  </g>  </svg>} href="https://www.aptible.com/docs/terraform">
    `Integration`

    Manage your Aptible resources programmatically via Terraform
  </Card>
</CardGroup>

## Network & Security

<CardGroup>
  <Card title="Google SSO" icon="google" href="https://www.aptible.com/docs/core-concepts/security-compliance/authentication/sso">
    `Integration`

    Configure SSO with Okta
  </Card>

  <Card title="Okta" icon={<svg fill="#E09600" width="30px" height="30px"  viewBox="0 0 16 16" xmlns="http://www.w3.org/2000/svg" fill="none"><path fill="#E09600" d="M8 1C4.143 1 1 4.12 1 8s3.121 7 7 7 7-3.121 7-7-3.143-7-7-7zm0 10.5c-1.94 0-3.5-1.56-3.5-3.5S6.06 4.5 8 4.5s3.5 1.56 3.5 3.5-1.56 3.5-3.5 3.5z"/></svg>} href="https://www.aptible.com/docs/core-concepts/security-compliance/authentication/sso">
    `Integration`

    Configure SSO with Okta
  </Card>

  <Card title="Single Sign-On (SAML)" icon="globe" href="https://www.aptible.com/docs/core-concepts/security-compliance/authentication/sso">
    `Custom`

    Configure SSO with Popular Identity Providers
  </Card>

  <Card title="SCIM (Provisioning)" icon="globe" href="https://www.aptible.com/docs/core-concepts/security-compliance/authentication/scim">
    `Custom`

    Configure SCIM with Popular Identity Providers
  </Card>

  <Card title="Site-to-site VPNs " icon="globe" href="https://www.aptible.com/docs/network-integrations">
    `Native`

    Connect to your Aptible resources with site-to-site VPNs
  </Card>

  <Card title="Twingate" icon={<svg version="1.0" xmlns="http://www.w3.org/2000/svg"  width="30px" height="30px" viewBox="0 0 275 275"  preserveAspectRatio="xMidYMid meet"> <metadata> </metadata> <g transform="translate(0.000000,300.000000) scale(0.100000,-0.100000)" fill="#E09600" stroke="none"> <path d="M1385 2248 c-160 -117 -317 -240 -351 -273 -121 -119 -124 -136 -124 -702 0 -244 3 -443 6 -443 3 0 66 42 140 93 l134 92 0 205 c1 468 10 487 342 728 l147 107 1 203 c0 111 -1 202 -3 202 -1 0 -133 -96 -292 -212z"/> <path d="M1781 1994 c-338 -249 -383 -286 -425 -348 -65 -96 -67 -109 -64 -624 l3 -462 225 156 c124 86 264 185 313 221 143 106 198 183 217 299 12 69 14 954 3 954 -5 -1 -127 -89 -272 -196z"/> </g> </svg>} href="https://www.aptible.com/docs/twingate">
    `Integration`

    Connect to your Aptible resources with a VPN alternative
  </Card>

  <Card title="VPC Peering" icon="globe" href="https://www.aptible.com/docs/network-integrations">
    `Native`

    Connect your external resources to Aptible resources with VPC Peering.
  </Card>
</CardGroup>

## Request New Integration

<Card title="Submit feature request" icon="plus" href="https://portal.productboard.com/aptible/2-aptible-roadmap-portal/tabs/5-ideas/submit-idea" />


# SolarWinds Integration
Source: https://www.aptible.com/docs/core-concepts/integrations/solarwinds

Learn about sending Aptible logs to SolarWinds

## Overview

SolarWinds Observability is a cloud-based platform for log management and analytics. With Aptible's integration, you can send logs directly to SolarWinds for analysis and storage.

## Set up

<Info> Prerequisites: A SolarWinds account</Info>

<Steps>
  <Step title="Configure your SolarWinds account for Aptible Log Ingestion">
    Refer to the [SolarWinds documentation](https://documentation.solarwinds.com/en/success_center/observability/content/configure/configure-logs.htm) for setting up your account to receive logs. Aptible sends logs securely via Syslog+TLS, and all we need is the syslog hostname and token from your SolarWinds account.

    Note: Like all Aptible Log Drain providers, SolarWinds also offers Business Associate Agreements (BAAs). To ensure HIPAA compliance, please contact them to execute a BAA.
  </Step>

  <Step title="Configure your Log Drain">
    You can send your Aptible logs directly to SolarWinds with a log drain. A SolarWinds Log Drain can be created in the following ways on Aptible:

    * Within the Aptible Dashboard by:
      * Navigating to an Environment
      * Selecting the **Log Drains** tab
      * Selecting **Create Log Drain**
      * Selecting **SolarWinds**
      * Entering your SolarWinds hostname
      * Entering your SolarWinds token
    * Using the [`aptible log_drain:create:solarwinds`](/docs/reference/aptible-cli/cli-commands/cli-log-drain-create-solarwinds) command
    * Using the [Aptible Terraform Provider](/docs/reference/terraform)
  </Step>
</Steps>


# Sumo Logic Integration
Source: https://www.aptible.com/docs/core-concepts/integrations/sumo-logic

Learn about sending Aptible logs to Sumo Logic

# Overview

[Sumo Logic](https://www.sumologic.com/) is a cloud-based log management and analytics platform. Aptible integrates with Sumo Logic, allowing logs to be sent directly to Sumo Logic for analysis and storage.

Sumo Logic signs BAAs and thus is a reliable log drain option for HIPAA compliance.

# Set up

<Info>  Prerequisites: A [Sumo Logic account](https://service.sumologic.com/ui/) </Info>

You can send your Aptible logs directly to Sumo Logic with a [log drain](/docs/core-concepts/observability/logs/log-drains/overview). A Sumo Logic log drain can be created in the following ways on Aptible:

* Within the Aptible Dashboard by:
  * Navigating to an Environment
  * Selecting the **Log Drains** tab
  * Selecting **Create Log Drain**
  * Selecting **Sumo Logic**
  * Filling the URL by creating a new [Hosted Collector](https://help.sumologic.com/docs/send-data/hosted-collectors/) in Sumologic using an HTTP source
* Using the [`aptible log_drain:create:sumologic`](/docs/reference/aptible-cli/cli-commands/cli-log-drain-create-sumologic) command


# Twingate Integration
Source: https://www.aptible.com/docs/core-concepts/integrations/twingate

Learn how to integrate Twingate with your Aptible account

# Overview

[Twingate](https://www.twingate.com/) is a VPN-alterative solution. Integrate Twingate with your Aptible account to provide Aptible users with secure and controlled access to Aptible resources -- without needing a VPN.

# Set up

[Learn more about integrating with Twingate here.](https://www.twingate.com/docs/aptible/)


# Database Credentials
Source: https://www.aptible.com/docs/core-concepts/managed-databases/connecting-databases/database-credentials



# Overview

When you provision a [Database](/docs/core-concepts/managed-databases/overview) on Aptible, you'll be provided with a set of Database Credentials.

<Warning>
  The password in Database Credentials should be protected for security.
</Warning>

Database Credentials are presented as connection URLs. Many libraries can use those directly, but you can always break down the URL into components.  The structure is:

<img alt="" />

<Accordion title="Accessing Database Credentials">
  Database Credentials can be accessed from the Aptible Dashboard by selecting the respective Database > selecting "Reveal" under "Credentials"

  <img alt="" />
</Accordion>

# Connecting to a Database using Database Credentials

There are three ways to connect to a Database using Database Credentials:

* **Direct Access:** This set of credentials is usable with [Network Integrations](/docs/core-concepts/integrations/network-integrations). This is also how [Apps](/docs/core-concepts/apps/overview), other [Databases](/docs/core-concepts/managed-databases/overview), and [Ephemeral SSH Sessions](/docs/core-concepts/apps/connecting-to-apps/ssh-sessions) within the [Stack](/docs/core-concepts/architecture/stacks) can contact the Database. Direct Access can be achieved by running the `aptible db:url` command and accessing the Database Credentials from the Aptible Dashboard.
* **Database Endpoint:** [Database Endpoints](/docs/core-concepts/managed-databases/connecting-databases/database-endpoints) allow users to expose Aptible Databases on the public internet. When another Database Endpoint is created, a separate set of Database Credentials is provided. Database Endpoints are useful if, for example, a third party needs to be granted access to the Aptible Database. This set of Database Credentials can be found in the Dashboard.
* **Database Tunnels:** The `aptible db:tunnel` CLI command allows users to create a [Database Tunnel](/docs/core-concepts/managed-databases/connecting-databases/database-tunnels), which provides a convenient, ad-hoc method for users to connect to Aptible Databases from a local workstation. Database Credentials are exposed in the terminal when you successfully tunnel and are only valid while the `db:tunnel` is up. Database Tunnels persist until the connection is closed or for a maximum of 24 hours.

<Tip>
  The Database Credentials provides credentials for the `aptible` user, but you can also create your own users for database types that support multiple users, such as PostgreSQL and MySQL. Refer to the database's own documentation for detailed instructions. If setting up a restricted user, review our [Setting Up Restricted User documentation](https://www.aptible.com/docs/core-concepts/managed-databases/connecting-databases/database-credentials#setting-up-a-restricted-user) for extra considerations.
</Tip>

Note that certain [Supported Databases](/docs/core-concepts/managed-databases/supported-databases/overview) provide multiple credentials. Refer to the respective Database documentation for more information.

# Connecting to Multiple Databases within your App

You can create multiple environment variables to store multiple database URLs, utilizing different variable names for each database. These can then be used in a database.yml file. The Aptible platform is agnostic as to how you store your DB configuration, as long as your are reading the added environment variables correctly.

If you have additional questions regarding configuring a Database.yml file, please contact [Aptible Support](https://app.aptible.com/support)

# Rotating Database Credentials

The only way to rotate Database Credentials without any downtime is to create separate Database users and update Apps to use the newly created user's credentials. Additionally, these separate users limit the impact of security vulnerabilities because applications are not granted more permissions than they need.

While using the built-in `aptible` user may be convenient for Databases that support it (MySQL, PostgreSQL, MongoDB, Elasticsearch 7). Aptible recommends creating a separate user that is granted only the minimum permissions required by the application.

The `aptible` user credentials can only be rotated by contacting [Aptible Support](https://contact.aptible.com). Please note that rotating the `aptible` user's credentials will involve an interruption to the app's availability.

# Setting Up a Restricted User

Aptible role management for the Environment is limited to what the Aptible user can do through the CLI or Dashboard; Database user management is separate.

You can create other database users on the Database with CREATE USER . However, this can lead to exposing the Database so that it can be accessed by this individual without giving them access to the aptible database user’s credentials. Traditionally, you use aptible db:tunnel to access the Database locally, but this command prints the tunnel URL with the aptible user credentials. This can lead to two main scenarios:

### If you don’t mind giving this individual access to the aptible credentials

Then you can give them Manage access to the Database’s Environment so they can tunnel into the database, and use the read-only user and password to log in via the tunnel. This is relatively easy to implement and can help prevent accidental writes but doesn’t ensure that this individual doesn’t login as aptible. The user would also have to remember not to copy/paste the aptible user credentials printed every time they tunnel.

### If this individual cannot have access to the aptible credentials

Then this user cannot have Manage access to the Database, which removes db:tunnel as an option.

* If the user only needs CLI access, you can create an App with a tool like psql installed on a different Environment on the same Stack. The user can aptible SSH into the App and use psql to access the Database using the read-only credentials. The Aptible user would require Manage access to this second Environment, but would not need any access to the Database’s Environment for this to work.
* If the user needs access from their private system, then you’ll have to create a Database Endpoint to expose the Database over the internet. We strongly recommend using [IP Filtering](https://www.aptible.com/docs/core-concepts/apps/connecting-to-apps/app-endpoints/ip-filtering#ip-filtering) to restrict access to the IP addresses or address ranges that they’ll be accessing the Database from so that the Database isn’t exposed to the entire internet for anyone to attempt to connect to.


# Database Endpoints
Source: https://www.aptible.com/docs/core-concepts/managed-databases/connecting-databases/database-endpoints



<img alt="Image" />

Database Endpoints let you expose a [Database](/docs/core-concepts/managed-databases/overview) to the public internet. <Info> The underlying AWS hardware that backs Database Endpoints has an idle connection timeout of 60 minutes. If clients need the connection to remain open longer they can work around this by periodically sending data over the connection (i.e., a "heartbeat") in order to keep it active.</Info>

<Accordion title="Creating a Database Endpoint">
  A Database Endpoint can be created in the following ways:

  1. Within the Aptible Dashboard by navigating to the respective Environment >selecting the respective Database > selecting the "Endpoints" tab > selecting "Create Endpoint"
  2. Using the [`aptible endpoints:database:create`](/docs/reference/aptible-cli/cli-commands/cli-endpoints-database-create) command
  3. Using the [Aptible Terraform Provider](/docs/reference/terraform)
</Accordion>

# IP Filtering

<img alt="Image" />

<Warning> To keep your data safe, it's highly recommended to enable IP filtering on Database Endpoints. If you do not enable filtering, your Database will be left open to the entire public internet, and it may be subject to potentially malicious traffic. If your database version is deprecated, you will be required to enable IP filtering.</Warning>

Like [App Endpoints](/docs/core-concepts/apps/connecting-to-apps/app-endpoints/overview), Database Endpoints support [IP Filtering](/docs/core-concepts/apps/connecting-to-apps/app-endpoints/ip-filtering) to restrict connections to your Database to a set of pre-approved IP addresses.

<Accordion title="Configuring IP Filtering">
  IP Filtering can be configured in the following ways:

  * Via the Aptible Dashboard when creating an Endpoint
  * By navigating to the Aptible Dashboard > selecting the respective Database > selecting the "Endpoints" tab > selecting "Edit"
</Accordion>

# Certificate Validation

<Warning> Not all Database clients will validate a Database server certificate by default. </Warning>

To ensure that you connect to the Database you intend to, you should ensure that your client performs full verification of the server certificate. Doing so will prevent Man-in-the-middle attacks of various types, such as address hijacking or DNS poisoning. You should consult the documentation for your client library to understand how to ensure it is properly configured to validate the certificate chain and the hostname.

For MySQL and PostgreSQL, you will need to retrieve a CA certificate using the [`aptible environment:ca_cert`](/docs/reference/aptible-cli/cli-commands/cli-environment-ca-cert) command in order to perform validation. After the Endpoint has been provisioned, the Database will also need to be restarted in order to update the Database's certificate to include the Endpoint's hostname. See the [Database Encryption in Transit](/docs/core-concepts/managed-databases/managing-databases/database-encryption/database-encryption-in-transit) page for more details.

If the remote service is not able to validate your database certificate, please [contact support](https://aptible.zendesk.com/hc/en-us/requests/new) for assistance.

# Least Privileged Access

<Warning> The provided [Database Credential](/docs/core-concepts/managed-databases/connecting-databases/database-credentials) has the full set of privileges needed to administer your Database, and we recommend that you *do not* provide this user/password to any external services. </Warning>

Create Database Users with the least privileges needed to use for integrations. For example, granting only "read" privileges to specific tables, such as those that do not contain your user's hashed passwords, is recommended when integrating a business intelligence reporting tool.

Please refer to database-specific documentation for guidance on user and permission management.
<Tip> Create a unique user for each external integration. Not only will this making auditing access easier, it will also allow you to rotate just the affected user's password in the unfortunate event of credentials being leaked by a third party</Tip>


# Database Tunnels
Source: https://www.aptible.com/docs/core-concepts/managed-databases/connecting-databases/database-tunnels



# Overview

Database Tunnels are ephemeral connections between your local workstation and a [Database](/docs/core-concepts/managed-databases/overview) running on Aptible. Database Tunnels are the most convenient way to get ad-hoc access to your Database. However, tunnels time out after 24 hours, so they're not ideal for long-term access or integrations. For those, you'll be better suited by [Database Endpoints](/docs/core-concepts/managed-databases/connecting-databases/database-endpoints).

<Warning> A Database Tunnel listens on `localhost`, and instructs you to connect via the host name `localhost.aptible.in`. Be aware that some software may make assumptions about this database based on the host name or IP, with possible consequences such as bypassing safeguards for running against a remote (production) database.</Warning>

# Getting Started

<Accordion title="Creating Database Tunnels">
  Database Tunnels can be created using the [`aptible db:tunnel`](/docs/reference/aptible-cli/cli-commands/cli-db-tunnel) command.
</Accordion>


# Connecting to Databases
Source: https://www.aptible.com/docs/core-concepts/managed-databases/connecting-databases/overview

Learn about the various ways to connect to your Database on Aptible

# Read more

<CardGroup>
  <Card title="Database Credentials" icon="book" href="https://www.aptible.com/docs/database-credentials">
    Connect your Database to other resources deployed on the same Stack
  </Card>

  <Card title="Database Tunnels" icon="book" href="https://www.aptible.com/docs/database-tunnels">
    Connect to your Database for ad-hoc access
  </Card>

  <Card title="Database Endpoints" icon="book" href="https://www.aptible.com/docs/database-endpoints">
    Connect your Database to the internet
  </Card>

  <Card title="Network Integrations" icon="book" href="">
    Connect your Database using network integrations such as VPC Peering and site-to-site VPN tunnels
  </Card>
</CardGroup>


# Database Backups
Source: https://www.aptible.com/docs/core-concepts/managed-databases/managing-databases/database-backups

Learn how Aptible snapshot backups, retention policies, and restore workflows protect your managed databases.

# Overview

Aptible provides several backup and recovery features for managed databases:

* Automatic daily backups
* Manual backups
* Cross-region copy backups
* Final backups for deprovisioned databases
* [Point-in-Time Recovery (PITR) for PostgreSQL](/docs/core-concepts/managed-databases/managing-databases/point-in-time-recovery)

All backups are compressed and encrypted. Snapshot-style backups are configured through the Environment's backup retention policy.

## How Backups Work

Aptible database backups are volume snapshots of the underlying database storage. Each snapshot is a read-only copy of the database volume captured when the backup is taken.

Once a snapshot is created, its contents do not change. You can restore, copy, or purge the snapshot according to the configured policy, but the backup itself remains immutable.

### Backup Portability

Aptible backups are not SQL dumps or compressed archive files. They are encrypted volume snapshots that rely on Aptible's database image, configuration, and restore tooling. Because of that design, Aptible-managed backups cannot be directly exported, mounted, or restored outside of Aptible.

If you need to move data to another platform or create a portable archive, export the data using database-native tools such as `pg_dump`, `pg_dumpall`, `mysqldump`, or the equivalent tool for your database engine.

<CardGroup>
  <Card title="Dump and restore PostgreSQL" icon="database" href="/how-to-guides/database-guides/dump-restore-postgresql" />

  <Card title="Dump and restore MySQL" icon="database" href="/how-to-guides/database-guides/dump-restore-mysql" />
</CardGroup>

If you plan to deprovision a Database but need to retain Aptible-managed backups for compliance or archival purposes, contact [Aptible Support](/docs/how-to-guides/troubleshooting/aptible-support) before deprovisioning so the relevant automatic backups can be converted to manual backups. Automatic backups are purged when the Database is deprovisioned unless retained by the Environment's final backup policy or converted to manual backups.

## Automatic Backups

By default, Aptible creates an automatic backup of each database every 24 hours. Retention is controlled by the Environment's backup retention policy.

The policy includes these settings:

* **Daily backups retained**: Number of daily backups retained. Default: `30`
* **Monthly backups retained**: Number of monthly backups retained, using the last backup of each month. Default: `12`
* **Yearly backups retained**: Number of yearly backups retained, using the last backup of each year. Default: `6`
* **Copy backups to another region**: Whether Aptible copies backups in the Environment to another region. Default: disabled
* **Keep final backup for deprovisioned databases**: Whether Aptible keeps a final backup when a database is deprovisioned. Default: enabled
* **Point-in-time Recovery for PostgreSQL**: Whether PITR retention is enabled for supported PostgreSQL databases. Default: Enabled
* **Days of PITR data retained**: How many days of PostgreSQL WAL data are retained for PITR. Default: `1`

<Tip>
  **Recommended backup retention policies**

  **Production environments:** Daily backups retained: 14-30, Monthly backups retained: 12, Yearly backups retained: 5, Copy backups to another region: enabled as needed for DR, Keep final backup for deprovisioned databases: enabled

  **Non-production environments:** Daily backups retained: 1-14, Monthly backups retained: 0, Yearly backups retained: 0, Copy backups to another region: disabled, Keep final backup for deprovisioned databases: disabled
</Tip>

## Backup Retention Policy for Automated Backups

Automatic backup retention and PostgreSQL PITR retention are configured at the Environment level through a shared backup retention policy.

You can modify the backup retention policy in these ways:

* In the Aptible Dashboard:
  * Select the Environment
  * Select the **Backups** tab
* Using the [`aptible backup_retention_policy:set`](/docs/reference/aptible-cli/cli-commands/cli-backup-retention-policy-set) CLI command
* Using the Aptible [Terraform Provider](https://registry.terraform.io/providers/aptible/aptible/latest/docs)

<Note>
  PITR retention appears in the Dashboard as **Point-in-time Recovery for PostgreSQL** and **Days of PITR data retained**. These PITR controls are not self-service configurable today. The current visible values are **Enabled** and **1**. If you need longer retention, contact [Aptible Support](/docs/how-to-guides/troubleshooting/aptible-support). For current PITR prerequisites, states, and restore guidance, see [Point-in-Time Recovery (PITR)](/docs/core-concepts/managed-databases/managing-databases/point-in-time-recovery).
</Note>

<Warning>
  Reducing retained backups, PITR data retention, cross-region copies, or final backups automatically deletes backup data that no longer matches the policy. This can permanently remove recovery data and may violate your organization's internal compliance controls.
</Warning>

<Tip>
  **Cost optimization tip:** [See this related blog for more recommendations for balancing continuity and costs](https://www.aptible.com/blog/backup-strategies-on-aptible-balancing-continuity-and-costs)
</Tip>

## Retention and Disposal

### Cross-region Copy Backups

When `COPY BACKUPS TO ANOTHER REGION` is enabled, Aptible copies backups in that Environment to a secondary region.

<Tip>
  Cross-region copy backups improve redundancy for disaster recovery. To improve recovery time objective (RTO), consider maintaining a secondary Stack in the destination region so you can restore more quickly during a regional outage.
</Tip>

The current cross-region mapping is:

<Note>
  Aptible guarantees that data processing and storage occur only within the US for US Stacks and within the EU for EU Stacks.
</Note>

| Originating region | Destination region(s)          |
| :----------------- | :----------------------------- |
| us-east-1          | us-west-1, us-west-2           |
| us-east-2          | us-west-1, us-west-2           |
| us-west-1          | us-east-1                      |
| us-west-2          | us-east-1                      |
| sa-east-1          | us-east-2                      |
| ca-central-1       | ca-west-1 (formerly us-east-2) |
| eu-west-1          | eu-central-1                   |
| eu-west-2          | eu-central-1                   |
| eu-west-3          | eu-central-1                   |
| eu-central-1       | eu-west-1                      |
| ap-northeast-1     | ap-northeast-2                 |
| ap-northeast-2     | ap-northeast-1                 |
| ap-southeast-1     | ap-northeast-2, ap-southeast-2 |
| ap-southeast-2     | ap-southeast-4                 |
| ap-south-1         | ap-southeast-2                 |

### Final Backups

When `KEEP FINAL BACKUP` is enabled, Aptible creates and retains one final backup when a database is deprovisioned. Final backups remain available as long as the Environment continues to retain them under policy.

<Tip>
  We strongly recommend enabling final backups for production Environments.
</Tip>

### Excluding a Database from New Automatic Backups

<Frame>
  <img alt="Disabling Backups" />
</Frame>

You can exclude an individual database from new automatic backups in the Aptible Dashboard from the database's **Settings** tab, or through the Aptible Terraform Provider.

If you disable backups for a database:

* Aptible stops taking new automatic backups for that database
* Aptible does not create a final backup during deprovisioning, even if the Environment policy normally retains final backups
* Existing backups are not deleted automatically

To purge older backups yourself:

* Use [`aptible backup:list DB_HANDLE`](/docs/reference/aptible-cli/cli-commands/cli-backup-list) to identify backups
* Use [`aptible backup:purge BACKUP_ID`](/docs/reference/aptible-cli/cli-commands/cli-backup-purge) to delete them
* Or export output as JSON:

```bash theme={null}
APTIBLE_OUTPUT_FORMAT=json aptible backup:list DB_HANDLE
```

## Manual Backups

Manual backups can be created at any time and are retained until you explicitly delete them, even after the source database is deprovisioned.

## Purging Backups

Automatic backups are permanently deleted when the associated database is deprovisioned unless retained as final backups. Final backups and cross-region copies that no longer match policy are also purged automatically. This cleanup process can take up to 1 hour.

You can also manually delete individual backups.

## Restoring from a Backup

Restoring from a backup creates a new database from the backed-up data. It does not replace or modify the source database.

By default, restored databases are created as a 1 GB [General Purpose (M) Container Profile](/docs/core-concepts/scaling/container-profiles#default-container-profile), though you can specify container size and profile with [`aptible backup:restore`](/docs/reference/aptible-cli/cli-commands/cli-backup-restore).

<Info>
  Databases backups are stored as EBS snapshots. Databases restored from a backup can initially have degraded disk performance, as described in AWS's ["Restoring from an Amazon EBS snapshot" documentation](https://docs.aws.amazon.com/prescriptive-guidance/latest/backup-recovery/restore.html). If you are using a restored database for performance testing, run the test twice: once to warm the restored volume, and a second time to measure steady-state performance. Restoring in the same region as the original backup generally minimizes initialization time.
</Info>

<Tip>
  If you have special retention needs, such as a litigation hold, contact [Aptible Support](/docs/how-to-guides/troubleshooting/aptible-support).
</Tip>

## Point-in-Time Recovery for PostgreSQL

Point-in-Time Recovery (PITR) is a feature available specifically for Aptible Managed **PostgreSQL** databases, allowing recovery to specific points in time, independent of automated, scheduled backups.

Visit the dedicated [Point-in-Time Recovery (PITR)](/docs/core-concepts/managed-databases/managing-databases/point-in-time-recovery) page to learn how to make the most of this feature.

## Encryption

Aptible's built-in [Database Encryption](/docs/core-concepts/managed-databases/managing-databases/database-encryption/overview) applies automatically to backups of a given database.

## FAQ

<AccordionGroup>
  <Accordion title="How do I modify an Environment's backup retention policy?">
    Backup retention policies can be modified in one of these ways:

    * Within the Aptible Dashboard:
      * Select the Environment
      * Select the **Backups** tab
    * Using the [`aptible backup_retention_policy:set`](/docs/reference/aptible-cli/cli-commands/cli-backup-retention-policy-set) CLI command
    * Using the Aptible [Terraform Provider](https://registry.terraform.io/providers/aptible/aptible/latest/docs)

      <img alt="Reviewing Backup Retention Policy in Aptible Dashboard" />
  </Accordion>

  <Accordion title="How do I view or manage automatic backups?">
    You can view automatic backups in two ways:

    * Using the [`aptible backup:list`](/docs/reference/aptible-cli/cli-commands/cli-backup-list) command
    * Within the Aptible Dashboard by navigating to the database's **Backups** tab
  </Accordion>

  <Accordion title="How do I view or manage final backups?">
    Final backups can be viewed in two ways:

    * Using the [`aptible backup:orphaned`](/docs/reference/aptible-cli/cli-commands/cli-backup-orphaned) command
    * Within the Aptible Dashboard by navigating to the Environment's **Backup Management** tab and selecting **Retained Backups of Deleted Databases**
  </Accordion>

  <Accordion title="How do I create manual backups?">
    Manual backups can be created in two ways:

    * Using the [`aptible db:backup`](/docs/reference/aptible-cli/cli-commands/cli-db-backup) command
    * Within the Aptible Dashboard by navigating to the database's **Backup Management** tab and selecting **Create Backup**
  </Accordion>

  <Accordion title="How do I delete a backup?">
    Backups can be deleted in these ways:

    * Using the [`aptible backup:purge`](/docs/reference/aptible-cli/cli-commands/cli-backup-purge) command
    * For active databases, in the Aptible Dashboard:
      * Navigate to the Environment
      * Select the database
      * Select the **Backups** tab
      * Select **Permanently remove this backup** for the backup you want to delete
    * For deprovisioned databases, in the Aptible Dashboard:
      * Navigate to the Environment
      * Select the **Backup Management** tab
      * Select **Delete** for the backup you want to remove

        <img alt="" />
  </Accordion>

  <Accordion title="How can I exclude a database from automatic backups?">
    * Navigate to the database
    * Select the **Settings** tab
    * Choose **Disabled: No new backups allowed** within **Database Backups**
  </Accordion>

  <Accordion title="How should I set my backup retention policy for production environments?">
    A typical production policy might look like this:

    * Yearly backups retained: 0-6
    * Monthly backups retained: 3-12
    * Daily backups retained: 15-60
  </Accordion>

  <Accordion title="How should I set my backup retention policy for non-production environments?">
    A typical non-production policy might look like this:

    * Yearly backups retained: 0
    * Monthly backups retained: 0-1
    * Daily backups retained: 1-7

    To optimize costs, it is usually best to disable cross-region copy backups and final backups in non-production environments.
  </Accordion>

  <Accordion title="How do I restore a backup?">
    You can restore a backup in these ways:

    * Using the [`aptible backup:restore`](/docs/reference/aptible-cli/cli-commands/cli-backup-restore) command
    * For active databases, within the Aptible Dashboard:
      * Navigate to the Environment
      * Select the database
      * Select the **Backups** tab
      * Select **Restore to a New Database** from the backup you want to restore
    * For deprovisioned databases, within the Aptible Dashboard:
      * Navigate to the Environment
      * Select the **Backup Management** tab
      * Select **Restore to a New Database** for the backup you want to restore

        <img alt="" />
  </Accordion>
</AccordionGroup>


# Application-Level Encryption
Source: https://www.aptible.com/docs/core-concepts/managed-databases/managing-databases/database-encryption/application-level-encryption



Aptible's built-in [Database Encryption](/docs/core-concepts/managed-databases/managing-databases/database-encryption/overview) is sufficient to comply with most data regulations, including HIPAA Technical Safeguards 45 C.F.R. § 164.312 (e)(2)(ii), but we strongly recommend also implementing application-level encryption in your App to further protect sensitive data.

The idea behind application-level encryption is simple: rather than store plaintext in your database, store encrypted data, then decrypt it on the fly in your app when fetching it from the database.

Using application-level encryption ensures that should an attacker get access to your database (e.g. through a SQL injection vulnerability in your app), they won't be able to extract data you encrypted unless they **also** compromise the keys you use to encrypt data at the application level.

The main downside of application-level encryption is that you cannot easily implement indices to search for this data. This is usually an acceptable tradeoff as long as you don't attempt to use application-level encryption on **everything**. There are, however, techniques that allow you to potentially work around this problem, such as [Homomorphic Encryption](https://en.wikipedia.org/wiki/Homomorphic_encryption).

> 📘 Don't roll your own encryption. There are a number of libraries for most application frameworks that can be used to implement application-level encryption.

# Key Rotation

Application-level encryption provides two main benefits over Aptible's built-in [Database Encryption](/docs/core-concepts/managed-databases/managing-databases/database-encryption/overview) and [Custom Database Encryption](/docs/core-concepts/managed-databases/managing-databases/database-encryption/custom-database-encryption) regarding rotating encryption keys.

## Key rotations are faster

Odds are, not all data is sensitive in your database.

If you are using application-level encryption, you only need to re-encrypt sensitive data when rotating the key, as opposed to having to re-encrypt **everything in your Database**.

This can be orders of magnitude faster than re-encrypting the disk. Indeed, consider that your Database stores a lot of things on disk which isn't strictly speaking data, such as indices, etc., which will inevitably be re-encrypted if you don't use application-level encryption.

## Zero-downtime key rotations are possible

Use the following approach to perform zero-downtime key rotations:

* Update your app so that it can **read** data encrypted with 2 different keys (the *old key*, and the *new key*). At this time, all your data remains encrypted with the *old key*.
* Update your app so that all new **writes** are encrypted using the *new key*.
* In the background, re-encrypt all your data with the *new key*. Once complete, all your data is now encrypted with the *new key*.
* Remove the *old key* from your app. At this stage, your app can no longer need any data encrypted with the *old key*, but that's OK because you just re-encrypted everything.
* Make sure to retain a copy of the *old key* so you can access data in backups that were performed before the key rotation


# Custom Database Encryption
Source: https://www.aptible.com/docs/core-concepts/managed-databases/managing-databases/database-encryption/custom-database-encryption



This section covers encryption using AWS Key Management Service. For more information about Aptible's default managed encryption, see [Database Encryption at rest](/docs/core-concepts/managed-databases/managing-databases/database-encryption/overview).

Aptible supports providing your own encryption key for [Database](/docs/core-concepts/managed-databases/overview) volumes using [AWS Key Management Service (KMS) customer-managed customer master keys (CMK)](https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#customer-cmk). This layer of encryption is applied in addition to Aptible’s existing Database Encryption. Encryption using AWS KMS CMKs is ideal for those who want to retain absolute control over when their data is destroyed or for those who need to rotate their database encryption keys regularly.

> ❗️ CMKs are completely managed outside of Aptible. As a result, if there is an issue accessing a CMK, Aptible will be unable to decrypt the data. **If a CMK is deleted, Aptible will be unable to recover the data.**

# Creating a New CMK

CMKs used by Aptible must be symmetric and must not use imported key material. The CMK must be created in the same region as the Database that will be using the key. Aptible can support all other CMK options.

After creating a CMK, the key must be shared with Aptible's AWS account. When creating the CMK in the AWS console, you can specify that you would like to share the CMK with the AWS account ID `916150859591`. Alternatively, you can include the following statements in the policy for the key:

```json theme={null}
{
    "Sid": "Allow use of the key",
    "Effect": "Allow",
    "Principal": {
        "AWS": "arn:aws:iam::916150859591:root"
    },
    "Action": [
        "kms:Encrypt",
        "kms:Decrypt",
        "kms:ReEncrypt*",
        "kms:GenerateDataKey*",
        "kms:DescribeKey"
    ],
    "Resource": "*"
},
{
    "Sid": "Allow attachment of persistent resources",
    "Effect": "Allow",
    "Principal": {
        "AWS": "arn:aws:iam::916150859591:root"
    },
    "Action": [
        "kms:CreateGrant",
        "kms:ListGrants",
        "kms:RevokeGrant"
    ],
    "Resource": "*",
    "Condition": {
        "Bool": {
            "kms:GrantIsForAWSResource": "true"
        }
    }
}
```

# Creating a new Database encrypted with a CMK

New databases encrypted with a CMK can be created via the Aptible CLI using the [`aptible db:create`](/docs/reference/aptible-cli/cli-commands/cli-db-create) command. The CMK should be passed in using the `--key-arn` flag, for example:

```shell theme={null}
aptible db:create $HANDLE --type $TYPE --key-arn arn:aws:kms:us-east-1:111111111111:key/aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee
```

# Key Rotation

Custom encryption keys can be rotated through AWS. However, this method does not re-encrypt the existing data as described in the [CMK key rotation](https://docs.aws.amazon.com/kms/latest/developerguide/rotate-keys.html) documentation. In order to do this, the key must be manually rotated by updating the CMK in Aptible.

# Updating CMKs

CMKs can be added or rotated by creating a backup and restoring from the backup via the Aptible CLI command [`aptible backup:restore`](/docs/reference/aptible-cli/cli-commands/cli-backup-restore)

```shell theme={null}
aptible backup:restore $BACKUP_ID --key-arn arn:aws:kms:us-east-1:111111111111:key/aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee
```

Rotating keys this way will inevitably cause downtime while the backup is restored. Therefore, if you need to conform to a strict key rotation schedule that requires all data to be re-encrypted, you may want to consider implementing [Application-Level Encryption](/docs/core-concepts/managed-databases/managing-databases/database-encryption/application-level-encryption) to reduce or possibly even mitigate downtime when rotating.

# Invalid CMKs

There are a number of reasons that a CMK might be invalid, including being created in the wrong region and failure to share the CMK with Aptible's AWS account.

When the CMK is unavailable, you will hit one of the following errors:

```
ERROR -- : SUMMARY: Execution failed because of:
ERROR -- : - FAILED: Create 10 GB database volume
WARN -- :
ERROR -- : There was an error creating the volume. If you are using a custom encryption key, this may be because you have not shared the key with Aptible.
```

```
ERROR -- : SUMMARY: Execution failed because of:
ERROR -- : - FAILED: Attach volume
```

To resolve this, you will need to ensure that the key has been correctly created and shared with Aptible.


# Database Encryption at Rest
Source: https://www.aptible.com/docs/core-concepts/managed-databases/managing-databases/database-encryption/database-encryption



This section covers Aptible's default managed encryption. For more information about encryption using AWS Key Management Service, see [Custom Database Encryption](/docs/core-concepts/managed-databases/managing-databases/database-encryption/custom-database-encryption).

Aptible automatically and transparently encrypts data at rest.

[Database](/docs/core-concepts/managed-databases/overview) encryption uses eCryptfs, and the algorithm used is either AES-192 or AES-256.

> 📘 You can determine whether your Database uses AES-192 or AES-256 for disk encryption through the Dashboard. New Databases will automatically use AES-256.

# Key Rotation

Aptible encrypts your data at the disk level. This means that to rotate the key used to encrypt your data, all data needs to be rewritten on disk using a new key. If you're not using [Custom Database Encryption](/docs/core-concepts/managed-databases/managing-databases/database-encryption/custom-database-encryption), you can do so by dumping the data from your database, then writing it to a new database, which will use a different key.

However, rotating keys this way will inevitably cause downtime while you dump and restore your data. This may take a long time if you have a lot of data.

Therefore, if you must conform to a strict key rotation schedule, we recommend implementing [Application-Level Encryption](/docs/core-concepts/managed-databases/managing-databases/database-encryption/application-level-encryption).


# Database Encryption in Transit
Source: https://www.aptible.com/docs/core-concepts/managed-databases/managing-databases/database-encryption/database-encryption-in-transit



Aptible [Databases](/docs/core-concepts/managed-databases/overview) are configured to allow connecting with SSL. Where possible, they are also configured to require SSL to ensure data is encrypted in transit. See the documentation for your [supported Database type](/docs/core-concepts/managed-databases/supported-databases/overview) for details on how it's configured.

# Trusted Certificates

Most supported database types use our wildcard `*.aptible.in` certificate for SSL / TLS termination and most clients should be able to use the local trust store to verify the validity of this certificate without issue. Depending on your client, you may still need to enable an option for force verification. Please see your client documentation for further details.

# Aptible CA Signed Certificates

While most Database types leverage the `*.aptible.in` certificate as above, other types (MySQL and PostgreSQL) have ways of revealing the private key as the provided default `aptible` user's permission set, so they cannot use this certificate without creating a security risk. In these cases, Deploy uses a Certificate Authority unique to each environment in order to a generate a server certificate for each of your databases.

The documentation for your [supported Database type](/docs/core-concepts/managed-databases/supported-databases/overview) will specify if it uses such a certificate: currently this applies to MySQL and PostgreSQL databases only.

In order to perform certificate verification for these databases, you will need to provide the CA certificate to your client. To retrieve the CA certificate required to verify the server certificate for your database, use the [`aptible environment:ca_cert`](/docs/reference/aptible-cli/cli-commands/cli-environment-ca-cert) command to retrieve the CA certificate for you environment(s).

# Self Signed Certificates

MySQL and PostgreSQL Databases that have been running since prior to January 15th, 2021 do not have a certificate generated by the Aptible CA as outlined above, but instead have a self-signed certificate installed. If this is the case for your database, all you need to do to move to an Aptible CA signed certificate is restart your database.

# Other Certificate Requirements

Contact [Aptible Support](/docs/how-to-guides/troubleshooting/aptible-support) if you have unique database server certificate constraints - we can accommodate installing a certificate that you provide if required.


# Database Encryption
Source: https://www.aptible.com/docs/core-concepts/managed-databases/managing-databases/database-encryption/overview



Aptible has built-in [Database Encryption](/docs/core-concepts/managed-databases/managing-databases/database-encryption/overview) that applies to all Aptible [Databases](/docs/core-concepts/managed-databases/overview) as well as the option to configure additional [Custom Database Encryption](/docs/core-concepts/managed-databases/managing-databases/database-encryption/custom-database-encryption). [Application-Level Encryption](/docs/core-concepts/managed-databases/managing-databases/database-encryption/application-level-encryption) may also be used, but this form of encryption is built into and used by your applications rather than being configured through Aptible.

# Backup Encryption

[Database Backups](/docs/core-concepts/managed-databases/managing-databases/database-backups) are taken as volume snapshots, so all forms of encryption used by the Database are applied automatically in backups.

***

**Keep reading:**

* [Database Encryption at Rest](/docs/core-concepts/managed-databases/managing-databases/database-encryption/database-encryption)
* [Custom Database Encryption](/docs/core-concepts/managed-databases/managing-databases/database-encryption/custom-database-encryption)
* [Application-Level Encryption](/docs/core-concepts/managed-databases/managing-databases/database-encryption/application-level-encryption)
* [Database Encryption in Transit](/docs/core-concepts/managed-databases/managing-databases/database-encryption/database-encryption-in-transit)


# Database Performance Tuning
Source: https://www.aptible.com/docs/core-concepts/managed-databases/managing-databases/database-tuning



# Database IOPS Performance

Database IOPS (Input/Output Operations Per Second) refer to the number of read/write [Operations](/docs/core-concepts/architecture/operations) that a Database can perform within a second.

**Baseline IOPS:**

* **gp3 Volume:** Aptible provisions new Databases with AWS gp3 volumes, which provide a minimum baseline IOPS performance of 3,000 IOPS no matter how small your volume is. The maximum IOPS depends on disk size, container profile, and container size. Disk size must meet a minimum ratio of 1 GB disk size per 500 IOPS. Review [this table](/docs/reference/aptible-cli/cli-commands/cli-db-modify#synopsis) for the required disk size, container profile, and container size.
* **gp2 Volume:** Older Databases may be using gp2 volumes, which provide a baseline IOPS performance of 3 IOPS / GB of disk, with a minimum allocation of 100 IOPS. In addition to the baseline performance, gp2 volumes also offer burst IOPS capacity up to 3,000 IOPS, which lets you exceed the baseline performance for a period of time. You should not rely on the volume's burst capacity during normal activity. Doing so will likely cause your performance to drop once you exhaust the volume's burst capacity, which will likely cause your app to go down.

Disk IO performance can be determined by viewing [Dashboard Metrics](/docs/core-concepts/observability/metrics/overview#dashboard-metrics) or monitoring [Metric Drains](/docs/core-concepts/observability/metrics/metrics-drains/overview) (`disk_read_iops` and `disk_write_iops` metrics).

IOPS can also be scaled on-demand to meet performance needs. For more information on scaling IOPS, refer to [Database Scaling.](/docs/core-concepts/scaling/database-scaling#iops-scaling)

# Database Throughput Performance

Database throughput performance refers to the amount of data that a database system can process in a given time period.

**Baseline Throughput:**

* **gp3 Volume:** gp3 volumes have a default throughput performance of 125MiB/s, and can be scaled up to 1,000MiB/s by contacting [Aptible Support](/docs/how-to-guides/troubleshooting/aptible-support).
* **gp2 Volume:** gp2 volumes have a maximum throughput performance of between 128MiB/s and 250MiB/s, depending on volume size. Volumes smaller or equal to 170 GB in size are allocated 128MiB/s of throughput. The throughput scales up until you reach a volume size of 334 GB. At 334 GB in size or larger, you have the full 250MiB/s performance possible with a GP2 volume. If you need more throughput, you may upgrade to a GP3 volume at any time by using the [`aptible db:modify`](/docs/reference/aptible-cli/cli-commands/cli-db-modify) command.

Database Throughput can be monitored within [Metric Drains](/docs/core-concepts/observability/metrics/metrics-drains/overview) (`disk_read_kbps` and `disk_write_kbps` metrics).

Database Throughput can be scaled by the Aptible Support Team only. For more information on scaling Throughput, refer to [Database Scaling.](/docs/core-concepts/scaling/database-scaling#throughput-performance)


# Database Upgrades
Source: https://www.aptible.com/docs/core-concepts/managed-databases/managing-databases/database-upgrade-methods



There are three supported methods for upgrading [Databases](/docs/core-concepts/managed-databases/overview):

* Dump and Restore
* Logical Replication
* Upgrading In-Place

<Tip> To review the available Database versions, use the [`aptible db:versions`](/docs/reference/aptible-cli/cli-commands/cli-db-versions) command.</Tip>

# Dump and Restore

Dump and Restore works by dumping the data from the existing Database and restoring it to a target Database, running the desired version. This method tends to require the most downtime to complete.

**Supported Databases:**

* All Database types support this upgrade method.

<Tip> This upgrade method is relatively simple and reliable and often allows upgrades across multiple major versions at once.</Tip>

## Process

1. Create a new target Database running the desired version.
2. Scale [Services](/docs/core-concepts/apps/deploying-apps/services) that use the existing Database down to zero containers. While this step is not strictly required, it ensures that the containers don't write to the Database during the upgrade.
3. Dump the data from the existing Database to the local filesystem.
4. Restore the data to the target Database from the local filesystem.
5. Update all of the Services that use the original Database to use the target Database.
6. Scale Services back up to their original container counts.

**Guides & Examples:**

* [How to dump and restore PostgreSQL](/docs/how-to-guides/database-guides/dump-restore-postgresql)

# Logical Replication

Logical replication works by creating an upgrade replica of the existing Database and updating all Services that currently use the existing Database to use the replica.

**Supported Databases:** [PostgreSQL](/docs/core-concepts/managed-databases/supported-databases/postgresql) Databases are currently the only ones that support this upgrade method.

<Tip> Upgrading using logical replication is a little more complex than the dump and restore method but only requires a fix amount of downtime regardless of the Database's size. This makes it is a good option for large, production [Databases](/docs/core-concepts/managed-databases/overview) that cannot tolerate much downtime. </Tip>

**Guides & Examples:**

* [How to upgrade PostgreSQL with logical replication](/docs/how-to-guides/database-guides/upgrade-postgresql)

# Upgrading In-Place

Upgrading Databases in-place works similarly to a "traditional" upgrade where, rather than replacing an existing Database instance with a new one, the existing instance is upgraded itself. This means that Services don't have to be updated to use the new instance, but it also makes it difficult or, in some cases, impossible to roll back if you find that a Service isn't compatible with the new version after upgrading.

Additionally, in-place upgrades generally don't work across multiple major versions, so the Database must be upgraded multiple times in situations like this.

Downtime for in-place upgrades varies.

In-place upgrades must be performed by [Aptible Support.](/docs/how-to-guides/troubleshooting/aptible-support)

**Supported Databases:**

* [MongoDB](/docs/core-concepts/managed-databases/supported-databases/mongodb) and [Redis](/docs/core-concepts/managed-databases/supported-databases/redis) have good support for in-place upgrades and, as such, can be upgraded fairly quickly and easily using this method.
* [ElasticSearch](/docs/core-concepts/managed-databases/supported-databases/elasticsearch) can generally be upgraded in-place but there are some exceptions:
  * ES 6.X and below can be upgraded up to ES 6.8
  * ES 7.X can be upgraded up to ES 7.10
    * ES 7 introduced breaking changes to the way the Database is hosted on Aptible so ES 6.X and below cannot be upgraded to ES 7.X in-place.
* [PostgreSQL](/docs/core-concepts/managed-databases/supported-databases/postgresql) supports in-place upgrades but the process is much more involved. As such, in-place upgrades for PostgreSQL Databases are reserved for when none of the other upgrade methods are viable.
  * Aptible will not offer in-place upgrades crossing from pre-15 PostgreSQL versions to PostgreSQL 15+ because of a [dependent change in glibc on the underlying Debian operating system](https://wiki.postgresql.org/wiki/Locale_data_changes). Instead, the following options are available to migrate existing pre-15 PostgreSQL databases to PostgreSQL 15+:
    * [Dump and restore PostgreSQL](/docs/how-to-guides/database-guides/dump-restore-postgresql)
    * [Upgrade PostgreSQL with logical replication](/docs/how-to-guides/database-guides/upgrade-postgresql)

**Guides & Examples:**

* [How to upgrade Redis](/docs/how-to-guides/database-guides/upgrade-redis)
* [How to upgrade MongoDB](/docs/how-to-guides/database-guides/upgrade-mongodb)


# Managing Databases
Source: https://www.aptible.com/docs/core-concepts/managed-databases/managing-databases/overview



# Overview

Aptible makes database management effortless by fully managing and monitoring your Aptible Databases 24/7. From scaling to backups, Aptible automatically ensures that your Databases are secure, optimized, and always available. Aptible handles the heavy lifting and provides additional controls and options, giving you the flexibility to manage aspects of your Databases when needed.

# Learn More

<AccordionGroup>
  <Accordion title="Scaling Databases">
    RAM/CPU, Disk, IOPS, and throughput can be scaled on-demand with minimal downtime (typically less than 1 minute) at any time via the Aptible Dashboard, CLI, or Terraform provider.

    Refer to [Database Scaling ](/docs/core-concepts/scaling/database-scaling)for more information.
  </Accordion>

  <Accordion title="Upgrading Databases">
    Aptible supports various methods for upgrading Databases, such as dump and restore, logical replication, and in-place upgrades.

    Refer to [Database Upgrades](/docs/core-concepts/managed-databases/managing-databases/database-upgrade-methods) for more information.
  </Accordion>

  <Accordion title="Backing up Databases">
    Aptible performs automatic daily backups of your databases every 24 hours. The default retention policy optimized for production environments, but this policy is fully customizable at the environment level, allowing you to configure daily, monthly, and yearly backups based on your requirements.

    In addition to automatic backups, you have the option to enable cross-region backups for disaster recovery and retain final backups of deprovisioned databases. Manual backups can be initiated at any time to provide additional flexibility and control over your data.

    Refer to [Database Backups](/docs/core-concepts/managed-databases/managing-databases/database-backups) for more information.
  </Accordion>

  <Accordion title="Replicating Databases">
    Aptible simplifies Database replication (PostgreSQL, MySQL, Redis) and clustering (MongoDB) databases in high-availability setups by automatically deploying the Database Containers across different Availability Zones (AZ).

    Refer to [Database Replication and Clustering](/docs/core-concepts/managed-databases/managing-databases/replication-clustering) for more information.
  </Accordion>

  <Accordion title="Encrypting Databases">
    Aptible has built-in Database Encryption that applies to all Databases, as well as the option to configure additional [Custom Database Encryption](/docs/core-concepts/managed-databases/managing-databases/database-encryption/custom-database-encryption). [Application-Level Encryption](/docs/core-concepts/managed-databases/managing-databases/database-encryption/application-level-encryption) may also be used.

    Refer to [Database Encryption](/docs/core-concepts/managed-databases/managing-databases/database-encryption/overview) for more information.
  </Accordion>

  <Accordion title="Restarting Databases">
    Databases can be restarted in the following ways:

    * Using the [`aptible db:restart`](/docs/reference/aptible-cli/cli-commands/cli-db-restart) command if you are also resizing the Database
    * Using the [`aptible db:reload`](/docs/reference/aptible-cli/cli-commands/cli-db-reload) command if you are not resizing the Database
      * Note: this command is faster to execute than `aptible db:restart`
    * Within the Aptible Dashboard, by:
      * Navigating to the database
      * Selecting the **Settings** tab
      * Selecting **Restart**
  </Accordion>

  <Accordion title="Renaming Databases">
    A Database can be renamed in the following ways:

    * Using the [`aptible db:rename`](/docs/reference/aptible-cli/cli-commands/cli-db-rename) command
    * Using the Aptible [Terraform Provider](https://registry.terraform.io/providers/aptible/aptible/latest/docs)

    For the change to take effect, the Database must be restarted.

    <Warning>Database handles cannot start with "internal-" or "sg-" because databases with these prefixes cannot have [Database Endpoints](/docs/core-concepts/managed-databases/connecting-databases/database-endpoints) allocated due to AWS limitations.</Warning>
  </Accordion>

  <Accordion title="Deprovisioning Databases">
    A Database can be deprovisioned in the following ways:

    * Using the [`aptible db:deprovision`](/docs/reference/aptible-cli/cli-commands/cli-db-deprovision) command
    * Using the Aptible [Terraform Provider](https://registry.terraform.io/providers/aptible/aptible/latest/docs)

    When a Database is deprovisioned, its [Database Backups](/docs/core-concepts/managed-databases/managing-databases/database-backups) are automatically deleted per the Environment's [Backup Retention Policy.](/docs/core-concepts/managed-databases/managing-databases/database-backups#backup-retention-policy-for-automated-backups)
  </Accordion>

  <Accordion title="Restoring Databases">
    A deprovisioned Database can be [restored from a Backup](/docs/core-concepts/managed-databases/managing-databases/database-backups#restoring-from-a-backup) as a new Database. The resulting Database will have the same data, username, and password as the original when the Backup was taken. Any [Database Endpoints](/docs/core-concepts/managed-databases/connecting-databases/database-endpoints) or [Replicas](/docs/core-concepts/managed-databases/managing-databases/replication-clustering) will have to be recreated.
  </Accordion>
</AccordionGroup>


# Point-in-Time Recovery (PITR)
Source: https://www.aptible.com/docs/core-concepts/managed-databases/managing-databases/point-in-time-recovery

Learn how PostgreSQL Point-in-Time Recovery works on Aptible, including prerequisites, recovery timing, and support guidance.

# Overview

Point-in-Time Recovery (PITR) lets you restore a PostgreSQL database to a specific moment in time instead of restoring only to the timestamp of a snapshot backup.

On Aptible, PITR uses PostgreSQL write-ahead log (WAL) archives together with snapshot backups in two stages:

1. Aptible restores a new database from the latest qualifying backup before your target time.
2. Aptible then replays archived WAL data up to the time you selected.

PITR is available for PostgreSQL 13 and newer.

<Info>
  PITR creates a new database. It does not overwrite or roll back the source database in place.
</Info>

## How PITR Relates to Backup Retention

PITR depends on the same Environment-level backup retention policy used for automatic backups.

To use PITR:

* The database must have backups enabled
* The database must already have retained WAL archive history for the time you want to recover to
* The database must be in a PITR-capable state. See [PITR States and Required Actions](#pitr-states-and-required-actions) below.

Enabling PITR retention does not by itself make every earlier point in time recoverable. A PITR restore can only succeed for times covered by the database's available WAL archive history.

PITR retention is not self-service configurable today. If you need longer retention, contact [Aptible Support](/docs/how-to-guides/troubleshooting/aptible-support).

<Note>
  In the current Dashboard UI, PITR retention appears in the Environment backup retention policy.
</Note>

For the retention policy settings themselves, see [Database Backups](/docs/core-concepts/managed-databases/managing-databases/database-backups#backup-retention-policy-for-automated-backups).
When setting the retention policy settings, the **Daily Backups Retained** value must be greater than the **Days of PITR Data Retained** value. Otherwise, PITR may be unsuccessful
in certain circumstances. This is because in order to replay WAL archive history, there must be a backup older than the oldest potential WAL entry within a date range to restore from.

## PITR States and Required Actions

If PITR is not enabled for your database, it will be in one of the states below. In these states, one or more prerequisites for performing PITR are not satisfied.

| State               | What it means                                                                                                                            | What to do                                                     |
| :------------------ | :--------------------------------------------------------------------------------------------------------------------------------------- | :------------------------------------------------------------- |
| Backups disabled    | PITR cannot run because database backups are disabled.                                                                                   | Re-enable backups for the database first.                      |
| Pending restart     | The database supports PITR, but it must be restarted before PITR can finish initializing.                                                | Restart the database, then PITR will initialize automatically. |
| Restricted          | PITR is unavailable for this database. In the current product, this state is used for special cases such as extremely high write volume. | Contact Aptible Support.                                       |
| Unsupported version | The database version does not support PITR.                                                                                              | Upgrade to PostgreSQL 13 or newer if PITR is required.         |

<Note>
  New PostgreSQL databases created through the Dashboard are initialized for PITR automatically when the Environment is already configured to retain PITR data.
</Note>

## Restoring with PITR

In the Aptible Dashboard:

1. Navigate to the Environment that contains the source database.
2. Select the database you want to recover.
3. Select the **Recovery** tab.
4. Enter a name for the new database.
5. Choose the **Target Time (UTC)**. For guidance on selecting a target time, see [Choosing a Recovery Time](#choosing-a-recovery-time) below.
6. Select **Start Recovery**.

The restore form creates a new database from the latest relevant backup and applies archived WAL data during provisioning until the selected time is reached.

<Frame>
  <img alt="Creating a Point-in-Time Restore" />
</Frame>

## Choosing a Recovery Time

When choosing a target time:

* You can recover only to times on or after the database's oldest available WAL archive time.
* In practice, choose a timestamp before the transaction or change you want to avoid restoring.
* WAL archiving happens asynchronously. Under normal conditions, WAL is available for PITR within about 5 minutes of a committed transaction.
* If you need to target a time within the last 5 minutes, the recovery may not succeed.

If the time you want is earlier than the oldest WAL archive still retained, PITR cannot recover to that moment.

## What to Expect During Recovery

PITR runs in two stages behind the scenes:

1. A new database is created from a qualifying snapshot backup.
2. Archived WAL data is replayed during provisioning until the requested recovery time is reached.

<Warning>
  The time it takes for a recovery operation to complete depends on how much WAL data must be replayed. For large databases, especially those around 500 GB disk size or more, with relatively high I/O activity, PITR can take several hours or longer to finish.
</Warning>

## Troubleshooting Insufficient WAL

If Aptible cannot replay enough WAL data to reach the requested time, the recovered database can fail to start.

One log message you may see is:

```text theme={null}
last completed transaction was at log time 2026-04-01 13:03:26.023332+00
```

This commonly means there were no transactions after the requested recovery time, so there was nothing to exclude during replay and the timestamp needs to be adjusted.

If this happens:

1. Do not retry the recovery yourself through the UI.
2. Leave the failed recovered database in place.
3. Contact [Aptible Support](/docs/how-to-guides/troubleshooting/aptible-support).

Support can retry the provisioning step with an adjusted timestamp without taking a new snapshot, which is faster and avoids repeating the initial restore stage unnecessarily.


# Database Replication and Clustering
Source: https://www.aptible.com/docs/core-concepts/managed-databases/managing-databases/replication-clustering



<Info> Database Replication and Clustering is only available on [Production and Enterprise](https://www.aptible.com/pricing)[ plans.](https://www.aptible.com/pricing)</Info>

Aptible simplifies Database replication (PostgreSQL, MySQL, Redis) and clustering (MongoDB) databases in high-availability setups by automatically deploying the Database Containers across different Availability Zones (AZ).

# Support by Database Type

Aptible supports replication or clustering for a number of [Databases](/docs/core-concepts/managed-databases/overview):

* [Redis:](/docs/core-concepts/managed-databases/supported-databases/redis) Aptible supports creating read-only replicas for Redis.
* [PostgreSQL:](/docs/core-concepts/managed-databases/supported-databases/postgresql) Aptible supports read-only hot standby replicas for PostgreSQL databases. PostgreSQL replicas utilize a [replication slot](https://www.postgresql.org/docs/current/warm-standby.html#STREAMING-REPLICATION-SLOTS) on the primary database which may increase WAL file retention on the primary. We recommend using a [Metric Drain](/docs/core-concepts/observability/metrics/metrics-drains/overview) to monitor disk usage on the primary Database. PostgreSQL Databases support [Logical Replication](/docs/how-to-guides/database-guides/upgrade-postgresql) using the [`aptible db:replicate`](/docs/reference/aptible-cli/cli-commands/cli-db-replicate) CLI command with the `--logical` flag for the purpose of upgrading the Database with minimal downtime.
* [MySQL:](/docs/core-concepts/managed-databases/supported-databases/mysql) Aptible supports creating replicas for MySQL Databases. While these replicas do not prevent writes from occurring, Aptible does not support writing to MySQL replicas. Any data written directly to a MySQL replica (and not the primary) may be lost.
* [MongoDB:](/docs/core-concepts/managed-databases/supported-databases/mongodb) Aptible supports creating MongoDB replica sets. To ensure that your replica is fault-tolerant, you should follow the [MongoDB recommendations for a number of instances in a replica set](https://docs.mongodb.com/manual/core/replica-set-architectures/#consider-fault-tolerance) when creating a replica set. We also recommend that you review the [readConcern](https://docs.mongodb.com/manual/reference/read-concern/), [writeConcern](https://docs.mongodb.com/manual/reference/write-concern/) and [connection url](https://docs.mongodb.com/manual/reference/connection-string/#replica-set-option) documentation to ensure that you are taking advantage of useful features offered by running a MongoDB replica set.

# Creating Replicas

Replicas can be created for supported databases using the [`aptible db:replicate`](/docs/reference/aptible-cli/cli-commands/cli-db-replicate) command. All new Replicas are created with the General Purpose (M) Container Profile, which is the [default Container Profile.](/docs/core-concepts/scaling/container-profiles#default-container-profile)

<Warning> Creating a replica on Aptible has a 6 hour timeout. While most Databases can be replicated in under 6 hours, some very large databases may take longer than 6 hours to create a replica. If your attempt to create a replica fails after hitting the 6 hour timeout, reach out to [Aptible Support](/docs/how-to-guides/troubleshooting/aptible-support). </Warning>


# Managed Databases 
Source: https://www.aptible.com/docs/core-concepts/managed-databases/overview

Learn about Aptible Managed Databases that automate provisioning, maintenance, and scaling

<Frame>
  <img alt="Databases Overview" />
</Frame>

## Overview

Aptible Databases provide data persistence and are automatically configured and managed by Aptible — including scaling, in-place upgrades, backups, database replication, network isolation, encryption, and more.

## Learn more about using Databases on Aptible

<CardGroup>
  <Card title="Provisioning Databases" icon="book" href="https://www.aptible.com/docs/provisioning-databases">
    Learn how to provision secure, fully Managed Databases
  </Card>

  <Card title="Connecting to Database" icon="book" href="https://www.aptible.com/docs/connecting-to-databases">
    Learn how to connect to your Apps, your team, or the internet to your Databases
  </Card>

  <Card title="Managing Databases" icon="book" href="https://www.aptible.com/docs/managing-databases">
    Learn how to scale, upgrade, backup, restore, or replicate your Databases
  </Card>
</CardGroup>

## Explore supported Database types

<Info>
  Custom Databases are not supported.
</Info>

<CardGroup>
  <Card title="Elasticsearch" icon={<svg xmlns="http://www.w3.org/2000/svg" width="30" height="30" viewBox="0 0 48 48"><path fill="#29b6f6" d="M37,24c0-3.314-2.686-6-6-6H5.918C5.323,19.894,5,21.909,5,24s0.323,4.106,0.918,6H31 C34.314,30,37,27.314,37,24z"/><path fill="#4db6ac" d="M25,44c6.524,0,12.305-3.133,15.954-7.968C38.835,34.151,36.055,33,33,33H7.157 C10.453,39.52,17.196,44,25,44z"/><path fill="#ffca28" d="M25,4C17.195,4,10.453,8.48,7.157,15H33c3.051,0,5.828-1.148,7.946-3.024 C37.299,7.138,31.525,4,25,4z"/><path fill="#f9a825" d="M22.073,15c-1.513-3.367-3.845-6.288-6.747-8.501C11.817,8.443,8.957,11.412,7.143,15H22.073z"/><path fill="#009688" d="M15.326,41.501c2.902-2.213,5.233-5.134,6.747-8.501H7.143 C8.957,36.588,11.817,39.557,15.326,41.501z"/><path fill="#212121" d="M5.928,18C5.332,19.895,5,21.907,5,24s0.332,4.105,0.928,6h17.234C23.703,28.092,24,26.081,24,24 s-0.297-4.092-0.837-6H5.928z"/></svg>} href="https://www.aptible.com/docs/elasticsearch" />

  <Card title="InfluxDB" icon={<svg xmlns="http://www.w3.org/2000/svg" width="30" height="30" viewBox="0 0 128 128"><path style={{fillRule:"evenodd",fill:"#020a47",fillOpacity:1}} d="m94.543 87.625 29.379-6.75a3.35 3.35 0 0 0 1.258-.543 3.358 3.358 0 0 0 1.383-2.305c.058-.46.019-.925-.114-1.37L113.957 22.34a3.499 3.499 0 0 0-1.59-2.14 3.49 3.49 0 0 0-2.633-.391l-29.37 6.75c-.887.23-1.65.8-2.118 1.593a3.452 3.452 0 0 0-.383 2.625L90.32 85.094a3.499 3.499 0 0 0 1.59 2.14c.79.477 1.738.618 2.633.391Zm-10.125 33.566 35.621-33.054c1.344-1.36 1.004-2.196-.844-1.528l-24.484 5.575a6.222 6.222 0 0 0-2.715 1.46 6.221 6.221 0 0 0-1.676 2.586l-7.425 23.954c-.508 1.855.168 2.363 1.523 1.007Zm-64.992-10.789 53.344 16.52c.91.172 1.851.012 2.656-.45a3.947 3.947 0 0 0 1.734-2.07l8.938-28.68a3.48 3.48 0 0 0 .117-1.378 3.492 3.492 0 0 0-.418-1.317 3.473 3.473 0 0 0-.89-1.058 3.562 3.562 0 0 0-1.227-.633L30.336 74.973a3.545 3.545 0 0 0-2.695.304 3.57 3.57 0 0 0-1.696 2.118l-8.879 28.62a3.556 3.556 0 0 0 .278 2.68 3.547 3.547 0 0 0 2.082 1.707ZM2.2 51.7l10.816 47.452c.336 1.856 1.207 1.856 1.68 0l7.425-23.949a6.709 6.709 0 0 0 .031-3.113 6.783 6.783 0 0 0-1.37-2.793L3.721 50.852c-1.183-1.395-2.066-1.008-1.523.847ZM43.906.973 3.046 38.875a3.47 3.47 0 0 0-.168 4.848l20.43 22.144a3.483 3.483 0 0 0 2.415 1.098 3.48 3.48 0 0 0 2.484-.926l40.848-37.965a3.446 3.446 0 0 0 .172-4.847L48.832 1.094A3.48 3.48 0 0 0 47.722.3a3.467 3.467 0 0 0-1.326-.3 3.419 3.419 0 0 0-1.34.238 3.435 3.435 0 0 0-1.149.735Zm39.496 85.804c1.864.508 3.035-.496 2.54-2.422L74.124 33.082c-.508-1.855-2.035-2.363-3.375-1.02L32.258 67.895c-1.352 1.343-1.016 2.859.836 3.367Zm20.09-71.515L56.898.972c-1.851-.511-2.187.169-.675 1.684l17.054 18.387a6.549 6.549 0 0 0 2.7 1.527 6.58 6.58 0 0 0 3.093.11l24.485-5.563c1.8-.508 1.8-1.355-.063-1.855Zm0 0"/></svg>} href="https://www.aptible.com/docs/influxdb" />

  <Card title="MySQL" icon="https://www.vectorlogo.zone/logos/mysql/mysql-icon.svg" href="https://www.aptible.com/docs/mysql" />

  <Card title="PostgreSQL" icon={<svg xmlns="http://www.w3.org/2000/svg" width="30" height="30" viewBox="0 0 48 48"><path fill="#fff" d="M44.083,29.79c-0.183-0.829-0.935-1.796-2.452-1.796c-0.31,0-0.649,0.039-1.035,0.119c-0.708,0.146-1.311,0.217-1.842,0.241c4.133-7.04,6.816-16.819,4.159-20.214c-3.501-4.473-8.214-5.141-10.711-5.141L31.967,3c-0.929,0.015-1.893,0.129-2.863,0.339l-3.583,0.774C25.033,4.052,24.536,4.009,24.018,4l-0.03,0l-0.016,0l-0.152-0.001c-1.593,0-3.046,0.338-4.341,0.973l-1.251-0.493c-1.72-0.678-4.308-1.485-6.868-1.485c-0.144,0-0.287,0.003-0.431,0.008C8.407,3.093,6.241,4.05,4.664,5.769C2.696,7.915,1.8,11.054,2.003,15.1C2.013,15.309,4.461,36,11.4,36h0.025l0.064-0.001c0.901-0.022,1.76-0.384,2.563-1.077c0.613,0.46,1.406,0.732,2.145,0.84c0.488,0.115,1.366,0.278,2.418,0.278c1.284,0,2.442-0.263,3.44-0.738c-0.001,0.88-0.006,1.994-0.016,3.418l-0.001,0.075l0.005,0.075c0.097,1.419,0.342,2.698,0.711,3.701c1.051,2.859,2.866,4.434,5.111,4.434c0.093,0,0.188-0.003,0.284-0.009c1.846-0.114,3.717-1.151,5.004-2.772c1.393-1.755,1.715-3.607,1.839-5.026L35,39.111v-0.088v-4.079l0.103,0.01l0.436,0.038l0.042,0.004l0.042,0.002c0.124,0.006,0.252,0.008,0.381,0.008c1.507,0,3.362-0.391,4.616-0.974C41.819,33.476,44.559,31.948,44.083,29.79z"/><path fill="#0277bd" d="M33,34c0-0.205,0.012-0.376,0.018-0.565C33.008,33.184,33,33,33,33s0.012-0.009,0.032-0.022c0.149-2.673,0.886-3.703,1.675-4.29c-0.11-0.153-0.237-0.318-0.356-0.475c-0.333-0.437-0.748-0.979-1.192-1.674l-0.082-0.158c-0.067-0.164-0.229-0.447-0.435-0.819c-1.183-2.14-3.645-6.592-1.96-9.404c0.738-1.232,2.122-1.942,4.121-2.117C33.986,11.718,30.925,6.115,23.985,6c-0.002,0-0.004,0-0.006,0c-6.041-0.098-8.026,5.392-8.672,8.672c0.89-0.377,1.906-0.606,2.836-0.606c0.014,0,0.029,0,0.043,0c2.29,0.017,3.865,1.239,4.323,3.354c0.335,1.552,0.496,2.91,0.492,4.153c-0.01,2.719-0.558,4.149-1.042,5.411l-0.154,0.408c-0.124,0.334-0.255,0.645-0.379,0.937c-0.126,0.298-0.237,0.563-0.318,0.802c0.484,0.11,0.864,0.265,1.125,0.38l0.151,0.066c0.047,0.02,0.094,0.043,0.137,0.069c0.848,0.516,1.376,1.309,1.489,2.233c0.061,0.498,0.051,3.893,0.03,6.855c0.087,1.285,0.305,2.364,0.593,3.146c0.409,1.114,1.431,3.241,3.394,3.119c1.37-0.085,2.687-0.919,3.561-2.019c0.938-1.181,1.284-2.487,1.414-3.958V34z"/><path fill="#0277bd" d="M15.114 28.917c-1.613-1.683-2.399-3.947-2.104-6.056.285-2.035.124-4.027.037-5.098-.029-.357-.048-.623-.047-.77 0-.008.002-.015.003-.023 0-.004-.002-.007-.002-.011.121-3.021 1.286-7.787 4.493-10.62C15.932 5.724 13.388 4.913 11 5 7.258 5.136 3.636 7.724 4 15c.137 2.73 3.222 19.103 7.44 19 .603-.015 1.229-.402 1.872-1.176 1.017-1.223 2.005-2.332 2.708-3.104C15.705 29.481 15.401 29.217 15.114 28.917zM37.023 14.731c.015.154.002.286-.022.408.031.92-.068 1.813-.169 2.677-.074.636-.15 1.293-.171 1.952-.021.645.07 1.282.166 1.956.225 1.578.459 3.359-.765 5.437.225.296.423.571.581.837 4.61-7.475 6.468-16.361 4.695-18.626C38.655 5.944 34.941 4.952 31.999 5c-.921.015-1.758.139-2.473.294C34.602 7.754 36.863 13.026 37.023 14.731zM41 30.071c-2.665.55-3.947.257-4.569-.126-.1.072-.2.133-.293.19-.372.225-.961.583-1.105 2.782.083.016.156.025.246.044L35.714 33c1.32.06 3.049-.31 4.063-.781C41.962 31.205 43.153 29.627 41 30.071zM22.023 32.119c-.037-.298-.198-.539-.492-.732l-.108-.047C21.062 31.181 20.653 31 20 31h-.004c-.127.01-.253.019-.38.019-.052 0-.103-.007-.155-.009-.474.365-1.148.647-2.816.99-2.98.759-1.221 1.655-.078 1.794 1.106.277 3.735.614 5.481-.809C22.043 32.537 22.035 32.229 22.023 32.119z"/><path fill="#0277bd" d="M20.681 18.501c-.292.302-.753.566-1.262.484-.828-.134-1.463-1.133-1.417-1.508h0c.044-.374.751-.569 1.578-.435.287.047.548.128.768.228-.32-.688-.899-1.085-1.782-1.182-1.565-.174-3.226.644-3.56 1.097.007.11.02.251.033.417.093 1.147.265 3.284-.05 5.537-.208 1.485.393 3.169 1.567 4.395.757.79 1.641 1.29 2.513 1.438.111-.478.309-.944.513-1.425.113-.265.233-.547.346-.852l.162-.427c.443-1.155.9-2.35.909-4.703C21.003 20.66 20.892 19.627 20.681 18.501zM34.847 22.007c-.104-.729-.211-1.484-.185-2.303.023-.742.105-1.442.184-2.119.062-.533.11-1.045.138-1.55-1.289.107-2.145.479-2.551 1.108.168-.057.358-.102.568-.129.892-.116 1.543.141 1.618.637.055.363-.253.705-.388.836-.277.269-.626.442-.981.488-.064.008-.129.012-.192.012-.353 0-.69-.121-.949-.3.112 1.973 1.567 4.612 2.283 5.907.153.277.271.498.369.688C35.154 24.163 35.009 23.143 34.847 22.007z"/></svg>} href="https://www.aptible.com/docs/postgresql" />

  <Card title="RabbitMQ" icon="https://www.rabbitmq.com/assets/files/rabbitmq-logo-e91cacd38fcef5219149bc5cfa10b384.svg" href="https://www.aptible.com/docs/rabbitmq" />

  <Card title="Redis" icon={<svg xmlns="http://www.w3.org/2000/svg" width="30" height="30" viewBox="0 0 48 48"><path fill="#b71c1c" d="M45,29.316c0-0.637-1.686-1.153-3.769-1.153c-1.812,0-3.32,0.391-3.683,0.911	c-3.586-1.694-7.173-3.388-10.759-5.083c-1.248-0.59-2.673-0.584-3.918,0.014c-3.818,1.837-7.636,3.674-11.454,5.511	c-0.864-0.126-1.907-0.201-3.032-0.201C5.408,29.316,3,29.832,3,30.469v3.46c0,0.033,0.033,0.064,0.045,0.096	c-0.146,0.555,0.07,1.205,0.649,1.478c5.641,2.665,11.281,5.329,16.922,7.994c1.432,0.677,3.068,0.671,4.496-0.016	c6.442-3.1,12.884-6.199,19.327-9.299c0.484-0.233,0.651-0.786,0.509-1.247C44.971,32.882,45,32.83,45,32.775V29.316z"/><path fill="#e53935" d="M20.616,39.158c-5.641-2.522-11.281-5.044-16.922-7.566c-0.922-0.412-0.926-1.727-0.007-2.146	c6.395-2.912,12.789-5.824,19.184-8.736c1.244-0.567,2.67-0.572,3.918-0.014c5.881,2.63,11.763,5.259,17.644,7.889	c0.754,0.337,0.758,1.414,0.006,1.756c-6.442,2.934-12.884,5.868-19.327,8.801C23.684,39.792,22.048,39.798,20.616,39.158z"/><path fill="#b71c1c" d="M45,21.675c0-0.637-1.686-1.153-3.769-1.153c-1.812,0-3.32,0.391-3.683,0.911	c-3.586-1.694-7.173-3.388-10.759-5.083c-1.248-0.59-2.673-0.584-3.918,0.014c-3.818,1.837-7.636,3.674-11.454,5.511	c-0.864-0.126-1.907-0.201-3.032-0.201C5.408,21.675,3,22.192,3,22.829v3.46c0,0.033,0.033,0.064,0.045,0.096	c-0.146,0.555,0.07,1.205,0.649,1.478c5.641,2.665,11.281,5.329,16.922,7.994c1.432,0.677,3.068,0.671,4.496-0.016	c6.442-3.1,12.884-6.199,19.327-9.299c0.484-0.233,0.651-0.786,0.509-1.247C44.971,25.242,45,25.19,45,25.135V21.675z"/><path fill="#e53935" d="M20.616,31.517c-5.641-2.522-11.281-5.044-16.922-7.566c-0.922-0.412-0.926-1.727-0.007-2.146	c6.395-2.912,12.789-5.824,19.184-8.736c1.244-0.567,2.67-0.572,3.918-0.014c5.881,2.63,11.763,5.259,17.644,7.889	c0.754,0.337,0.758,1.414,0.006,1.756c-6.442,2.934-12.884,5.868-19.327,8.801C23.684,32.152,22.048,32.158,20.616,31.517z"/><path fill="#b71c1c" d="M45,14.035c0-0.637-1.686-1.153-3.769-1.153c-1.812,0-3.32,0.391-3.683,0.911	c-3.586-1.694-7.173-3.388-10.759-5.083c-1.248-0.59-2.673-0.584-3.918,0.014c-3.818,1.837-7.636,3.674-11.454,5.511	c-0.864-0.126-1.907-0.201-3.032-0.201C5.408,14.035,3,14.551,3,15.188v3.46c0,0.033,0.033,0.064,0.045,0.096	c-0.146,0.555,0.07,1.205,0.649,1.478c5.641,2.665,11.281,5.329,16.922,7.994c1.432,0.677,3.068,0.671,4.496-0.016	c6.442-3.1,12.884-6.199,19.327-9.299c0.484-0.233,0.651-0.786,0.509-1.247C44.971,17.601,45,17.549,45,17.494V14.035z"/><path fill="#e53935" d="M20.616,23.877c-5.641-2.522-11.281-5.044-16.922-7.566c-0.922-0.412-0.926-1.727-0.007-2.146	c6.395-2.912,12.789-5.824,19.184-8.736c1.244-0.567,2.67-0.572,3.918-0.014c5.881,2.63,11.763,5.259,17.644,7.889	c0.754,0.337,0.758,1.414,0.006,1.756c-6.442,2.934-12.884,5.868-19.327,8.801C23.684,24.512,22.048,24.517,20.616,23.877z"/><path fill="#fff" d="M18.748,14.741c-0.002,1.042-2.762,2.057-5.093,2.086c-2.419,0.03-5.273-0.993-5.282-2.051	c-0.009-1.061,2.842-2.161,5.311-2.135C16.017,12.665,18.751,13.703,18.748,14.741z"/><path fill="#fff" d="M17.038,18.471c2.393,1.022,4.785,2.045,7.178,3.067c1.054-1.56,2.108-3.12,3.162-4.68	C23.931,17.396,20.485,17.934,17.038,18.471z"/><path fill="#fff" d="M21.86,9.775c-1.101,0.401-2.203,0.801-3.304,1.202c1.507,0.132,3.015,0.264,4.522,0.395	c0.48,0.796,0.959,1.592,1.439,2.387c0.295-0.722,0.59-1.444,0.885-2.166c1.286-0.1,2.572-0.2,3.858-0.3	c-0.997-0.419-1.994-0.839-2.991-1.259c0.254-0.608,0.508-1.216,0.762-1.825c-0.97,0.29-1.939,0.58-2.909,0.87	c-1.07-0.422-2.14-0.843-3.21-1.265C21.228,8.468,21.544,9.122,21.86,9.775z"/><path fill="#b71c1c" d="M27.267,14.619c2.271-0.906,4.543-1.813,6.814-2.719c1.962,0.834,3.924,1.668,5.886,2.502	c-2.202,0.876-4.403,1.752-6.605,2.629C31.331,16.226,29.299,15.423,27.267,14.619z"/><path fill="#a01c1c" d="M34.082,11.963c-0.005,1.596-0.01,3.191-0.015,4.787c1.967-0.783,3.934-1.565,5.901-2.348	C38.006,13.589,36.044,12.776,34.082,11.963z"/></svg>} href="https://www.aptible.com/docs/redis" />

  <Card title="SFTP" icon="file" href="https://www.aptible.com/docs/sftp" />

  <Card title="See all" icon="grid" href="https://www.aptible.com/docs/core-concepts/managed-databases/supported-databases/overview" />
</CardGroup>


# Provisioning Databases
Source: https://www.aptible.com/docs/core-concepts/managed-databases/provisioning-databases

Learn about provisioning Managed Databases on Aptible

# Overview

Aptible provides a platform to provision secure, reliable, Managed Databases in a single click.

# Explore Supported Databases

<CardGroup>
  <Card title="Elasticsearch" icon={<svg xmlns="http://www.w3.org/2000/svg" width="30" height="30" viewBox="0 0 48 48"><path fill="#29b6f6" d="M37,24c0-3.314-2.686-6-6-6H5.918C5.323,19.894,5,21.909,5,24s0.323,4.106,0.918,6H31 C34.314,30,37,27.314,37,24z"/><path fill="#4db6ac" d="M25,44c6.524,0,12.305-3.133,15.954-7.968C38.835,34.151,36.055,33,33,33H7.157 C10.453,39.52,17.196,44,25,44z"/><path fill="#ffca28" d="M25,4C17.195,4,10.453,8.48,7.157,15H33c3.051,0,5.828-1.148,7.946-3.024 C37.299,7.138,31.525,4,25,4z"/><path fill="#f9a825" d="M22.073,15c-1.513-3.367-3.845-6.288-6.747-8.501C11.817,8.443,8.957,11.412,7.143,15H22.073z"/><path fill="#009688" d="M15.326,41.501c2.902-2.213,5.233-5.134,6.747-8.501H7.143 C8.957,36.588,11.817,39.557,15.326,41.501z"/><path fill="#212121" d="M5.928,18C5.332,19.895,5,21.907,5,24s0.332,4.105,0.928,6h17.234C23.703,28.092,24,26.081,24,24 s-0.297-4.092-0.837-6H5.928z"/></svg>} href="https://www.aptible.com/docs/elasticsearch" />

  <Card title="InfluxDB" icon={<svg xmlns="http://www.w3.org/2000/svg" width="30" height="30" viewBox="0 0 128 128"><path style={{fillRule:"evenodd",fill:"#020a47",fillOpacity:1}} d="m94.543 87.625 29.379-6.75a3.35 3.35 0 0 0 1.258-.543 3.358 3.358 0 0 0 1.383-2.305c.058-.46.019-.925-.114-1.37L113.957 22.34a3.499 3.499 0 0 0-1.59-2.14 3.49 3.49 0 0 0-2.633-.391l-29.37 6.75c-.887.23-1.65.8-2.118 1.593a3.452 3.452 0 0 0-.383 2.625L90.32 85.094a3.499 3.499 0 0 0 1.59 2.14c.79.477 1.738.618 2.633.391Zm-10.125 33.566 35.621-33.054c1.344-1.36 1.004-2.196-.844-1.528l-24.484 5.575a6.222 6.222 0 0 0-2.715 1.46 6.221 6.221 0 0 0-1.676 2.586l-7.425 23.954c-.508 1.855.168 2.363 1.523 1.007Zm-64.992-10.789 53.344 16.52c.91.172 1.851.012 2.656-.45a3.947 3.947 0 0 0 1.734-2.07l8.938-28.68a3.48 3.48 0 0 0 .117-1.378 3.492 3.492 0 0 0-.418-1.317 3.473 3.473 0 0 0-.89-1.058 3.562 3.562 0 0 0-1.227-.633L30.336 74.973a3.545 3.545 0 0 0-2.695.304 3.57 3.57 0 0 0-1.696 2.118l-8.879 28.62a3.556 3.556 0 0 0 .278 2.68 3.547 3.547 0 0 0 2.082 1.707ZM2.2 51.7l10.816 47.452c.336 1.856 1.207 1.856 1.68 0l7.425-23.949a6.709 6.709 0 0 0 .031-3.113 6.783 6.783 0 0 0-1.37-2.793L3.721 50.852c-1.183-1.395-2.066-1.008-1.523.847ZM43.906.973 3.046 38.875a3.47 3.47 0 0 0-.168 4.848l20.43 22.144a3.483 3.483 0 0 0 2.415 1.098 3.48 3.48 0 0 0 2.484-.926l40.848-37.965a3.446 3.446 0 0 0 .172-4.847L48.832 1.094A3.48 3.48 0 0 0 47.722.3a3.467 3.467 0 0 0-1.326-.3 3.419 3.419 0 0 0-1.34.238 3.435 3.435 0 0 0-1.149.735Zm39.496 85.804c1.864.508 3.035-.496 2.54-2.422L74.124 33.082c-.508-1.855-2.035-2.363-3.375-1.02L32.258 67.895c-1.352 1.343-1.016 2.859.836 3.367Zm20.09-71.515L56.898.972c-1.851-.511-2.187.169-.675 1.684l17.054 18.387a6.549 6.549 0 0 0 2.7 1.527 6.58 6.58 0 0 0 3.093.11l24.485-5.563c1.8-.508 1.8-1.355-.063-1.855Zm0 0"/></svg>} href="https://www.aptible.com/docs/influxdb" />

  <Card title="MySQL" icon="https://www.vectorlogo.zone/logos/mysql/mysql-icon.svg" href="https://www.aptible.com/docs/mysql" />

  <Card title="PostgreSQL" icon={<svg xmlns="http://www.w3.org/2000/svg" width="30" height="30" viewBox="0 0 48 48"><path fill="#fff" d="M44.083,29.79c-0.183-0.829-0.935-1.796-2.452-1.796c-0.31,0-0.649,0.039-1.035,0.119c-0.708,0.146-1.311,0.217-1.842,0.241c4.133-7.04,6.816-16.819,4.159-20.214c-3.501-4.473-8.214-5.141-10.711-5.141L31.967,3c-0.929,0.015-1.893,0.129-2.863,0.339l-3.583,0.774C25.033,4.052,24.536,4.009,24.018,4l-0.03,0l-0.016,0l-0.152-0.001c-1.593,0-3.046,0.338-4.341,0.973l-1.251-0.493c-1.72-0.678-4.308-1.485-6.868-1.485c-0.144,0-0.287,0.003-0.431,0.008C8.407,3.093,6.241,4.05,4.664,5.769C2.696,7.915,1.8,11.054,2.003,15.1C2.013,15.309,4.461,36,11.4,36h0.025l0.064-0.001c0.901-0.022,1.76-0.384,2.563-1.077c0.613,0.46,1.406,0.732,2.145,0.84c0.488,0.115,1.366,0.278,2.418,0.278c1.284,0,2.442-0.263,3.44-0.738c-0.001,0.88-0.006,1.994-0.016,3.418l-0.001,0.075l0.005,0.075c0.097,1.419,0.342,2.698,0.711,3.701c1.051,2.859,2.866,4.434,5.111,4.434c0.093,0,0.188-0.003,0.284-0.009c1.846-0.114,3.717-1.151,5.004-2.772c1.393-1.755,1.715-3.607,1.839-5.026L35,39.111v-0.088v-4.079l0.103,0.01l0.436,0.038l0.042,0.004l0.042,0.002c0.124,0.006,0.252,0.008,0.381,0.008c1.507,0,3.362-0.391,4.616-0.974C41.819,33.476,44.559,31.948,44.083,29.79z"/><path fill="#0277bd" d="M33,34c0-0.205,0.012-0.376,0.018-0.565C33.008,33.184,33,33,33,33s0.012-0.009,0.032-0.022c0.149-2.673,0.886-3.703,1.675-4.29c-0.11-0.153-0.237-0.318-0.356-0.475c-0.333-0.437-0.748-0.979-1.192-1.674l-0.082-0.158c-0.067-0.164-0.229-0.447-0.435-0.819c-1.183-2.14-3.645-6.592-1.96-9.404c0.738-1.232,2.122-1.942,4.121-2.117C33.986,11.718,30.925,6.115,23.985,6c-0.002,0-0.004,0-0.006,0c-6.041-0.098-8.026,5.392-8.672,8.672c0.89-0.377,1.906-0.606,2.836-0.606c0.014,0,0.029,0,0.043,0c2.29,0.017,3.865,1.239,4.323,3.354c0.335,1.552,0.496,2.91,0.492,4.153c-0.01,2.719-0.558,4.149-1.042,5.411l-0.154,0.408c-0.124,0.334-0.255,0.645-0.379,0.937c-0.126,0.298-0.237,0.563-0.318,0.802c0.484,0.11,0.864,0.265,1.125,0.38l0.151,0.066c0.047,0.02,0.094,0.043,0.137,0.069c0.848,0.516,1.376,1.309,1.489,2.233c0.061,0.498,0.051,3.893,0.03,6.855c0.087,1.285,0.305,2.364,0.593,3.146c0.409,1.114,1.431,3.241,3.394,3.119c1.37-0.085,2.687-0.919,3.561-2.019c0.938-1.181,1.284-2.487,1.414-3.958V34z"/><path fill="#0277bd" d="M15.114 28.917c-1.613-1.683-2.399-3.947-2.104-6.056.285-2.035.124-4.027.037-5.098-.029-.357-.048-.623-.047-.77 0-.008.002-.015.003-.023 0-.004-.002-.007-.002-.011.121-3.021 1.286-7.787 4.493-10.62C15.932 5.724 13.388 4.913 11 5 7.258 5.136 3.636 7.724 4 15c.137 2.73 3.222 19.103 7.44 19 .603-.015 1.229-.402 1.872-1.176 1.017-1.223 2.005-2.332 2.708-3.104C15.705 29.481 15.401 29.217 15.114 28.917zM37.023 14.731c.015.154.002.286-.022.408.031.92-.068 1.813-.169 2.677-.074.636-.15 1.293-.171 1.952-.021.645.07 1.282.166 1.956.225 1.578.459 3.359-.765 5.437.225.296.423.571.581.837 4.61-7.475 6.468-16.361 4.695-18.626C38.655 5.944 34.941 4.952 31.999 5c-.921.015-1.758.139-2.473.294C34.602 7.754 36.863 13.026 37.023 14.731zM41 30.071c-2.665.55-3.947.257-4.569-.126-.1.072-.2.133-.293.19-.372.225-.961.583-1.105 2.782.083.016.156.025.246.044L35.714 33c1.32.06 3.049-.31 4.063-.781C41.962 31.205 43.153 29.627 41 30.071zM22.023 32.119c-.037-.298-.198-.539-.492-.732l-.108-.047C21.062 31.181 20.653 31 20 31h-.004c-.127.01-.253.019-.38.019-.052 0-.103-.007-.155-.009-.474.365-1.148.647-2.816.99-2.98.759-1.221 1.655-.078 1.794 1.106.277 3.735.614 5.481-.809C22.043 32.537 22.035 32.229 22.023 32.119z"/><path fill="#0277bd" d="M20.681 18.501c-.292.302-.753.566-1.262.484-.828-.134-1.463-1.133-1.417-1.508h0c.044-.374.751-.569 1.578-.435.287.047.548.128.768.228-.32-.688-.899-1.085-1.782-1.182-1.565-.174-3.226.644-3.56 1.097.007.11.02.251.033.417.093 1.147.265 3.284-.05 5.537-.208 1.485.393 3.169 1.567 4.395.757.79 1.641 1.29 2.513 1.438.111-.478.309-.944.513-1.425.113-.265.233-.547.346-.852l.162-.427c.443-1.155.9-2.35.909-4.703C21.003 20.66 20.892 19.627 20.681 18.501zM34.847 22.007c-.104-.729-.211-1.484-.185-2.303.023-.742.105-1.442.184-2.119.062-.533.11-1.045.138-1.55-1.289.107-2.145.479-2.551 1.108.168-.057.358-.102.568-.129.892-.116 1.543.141 1.618.637.055.363-.253.705-.388.836-.277.269-.626.442-.981.488-.064.008-.129.012-.192.012-.353 0-.69-.121-.949-.3.112 1.973 1.567 4.612 2.283 5.907.153.277.271.498.369.688C35.154 24.163 35.009 23.143 34.847 22.007z"/></svg>} href="https://www.aptible.com/docs/postgresql" />

  <Card title="RabbitMQ" icon="https://www.rabbitmq.com/assets/files/rabbitmq-logo-e91cacd38fcef5219149bc5cfa10b384.svg" href="https://www.aptible.com/docs/rabbitmq" />

  <Card title="Redis" icon={<svg xmlns="http://www.w3.org/2000/svg" width="30" height="30" viewBox="0 0 48 48"><path fill="#b71c1c" d="M45,29.316c0-0.637-1.686-1.153-3.769-1.153c-1.812,0-3.32,0.391-3.683,0.911	c-3.586-1.694-7.173-3.388-10.759-5.083c-1.248-0.59-2.673-0.584-3.918,0.014c-3.818,1.837-7.636,3.674-11.454,5.511	c-0.864-0.126-1.907-0.201-3.032-0.201C5.408,29.316,3,29.832,3,30.469v3.46c0,0.033,0.033,0.064,0.045,0.096	c-0.146,0.555,0.07,1.205,0.649,1.478c5.641,2.665,11.281,5.329,16.922,7.994c1.432,0.677,3.068,0.671,4.496-0.016	c6.442-3.1,12.884-6.199,19.327-9.299c0.484-0.233,0.651-0.786,0.509-1.247C44.971,32.882,45,32.83,45,32.775V29.316z"/><path fill="#e53935" d="M20.616,39.158c-5.641-2.522-11.281-5.044-16.922-7.566c-0.922-0.412-0.926-1.727-0.007-2.146	c6.395-2.912,12.789-5.824,19.184-8.736c1.244-0.567,2.67-0.572,3.918-0.014c5.881,2.63,11.763,5.259,17.644,7.889	c0.754,0.337,0.758,1.414,0.006,1.756c-6.442,2.934-12.884,5.868-19.327,8.801C23.684,39.792,22.048,39.798,20.616,39.158z"/><path fill="#b71c1c" d="M45,21.675c0-0.637-1.686-1.153-3.769-1.153c-1.812,0-3.32,0.391-3.683,0.911	c-3.586-1.694-7.173-3.388-10.759-5.083c-1.248-0.59-2.673-0.584-3.918,0.014c-3.818,1.837-7.636,3.674-11.454,5.511	c-0.864-0.126-1.907-0.201-3.032-0.201C5.408,21.675,3,22.192,3,22.829v3.46c0,0.033,0.033,0.064,0.045,0.096	c-0.146,0.555,0.07,1.205,0.649,1.478c5.641,2.665,11.281,5.329,16.922,7.994c1.432,0.677,3.068,0.671,4.496-0.016	c6.442-3.1,12.884-6.199,19.327-9.299c0.484-0.233,0.651-0.786,0.509-1.247C44.971,25.242,45,25.19,45,25.135V21.675z"/><path fill="#e53935" d="M20.616,31.517c-5.641-2.522-11.281-5.044-16.922-7.566c-0.922-0.412-0.926-1.727-0.007-2.146	c6.395-2.912,12.789-5.824,19.184-8.736c1.244-0.567,2.67-0.572,3.918-0.014c5.881,2.63,11.763,5.259,17.644,7.889	c0.754,0.337,0.758,1.414,0.006,1.756c-6.442,2.934-12.884,5.868-19.327,8.801C23.684,32.152,22.048,32.158,20.616,31.517z"/><path fill="#b71c1c" d="M45,14.035c0-0.637-1.686-1.153-3.769-1.153c-1.812,0-3.32,0.391-3.683,0.911	c-3.586-1.694-7.173-3.388-10.759-5.083c-1.248-0.59-2.673-0.584-3.918,0.014c-3.818,1.837-7.636,3.674-11.454,5.511	c-0.864-0.126-1.907-0.201-3.032-0.201C5.408,14.035,3,14.551,3,15.188v3.46c0,0.033,0.033,0.064,0.045,0.096	c-0.146,0.555,0.07,1.205,0.649,1.478c5.641,2.665,11.281,5.329,16.922,7.994c1.432,0.677,3.068,0.671,4.496-0.016	c6.442-3.1,12.884-6.199,19.327-9.299c0.484-0.233,0.651-0.786,0.509-1.247C44.971,17.601,45,17.549,45,17.494V14.035z"/><path fill="#e53935" d="M20.616,23.877c-5.641-2.522-11.281-5.044-16.922-7.566c-0.922-0.412-0.926-1.727-0.007-2.146	c6.395-2.912,12.789-5.824,19.184-8.736c1.244-0.567,2.67-0.572,3.918-0.014c5.881,2.63,11.763,5.259,17.644,7.889	c0.754,0.337,0.758,1.414,0.006,1.756c-6.442,2.934-12.884,5.868-19.327,8.801C23.684,24.512,22.048,24.517,20.616,23.877z"/><path fill="#fff" d="M18.748,14.741c-0.002,1.042-2.762,2.057-5.093,2.086c-2.419,0.03-5.273-0.993-5.282-2.051	c-0.009-1.061,2.842-2.161,5.311-2.135C16.017,12.665,18.751,13.703,18.748,14.741z"/><path fill="#fff" d="M17.038,18.471c2.393,1.022,4.785,2.045,7.178,3.067c1.054-1.56,2.108-3.12,3.162-4.68	C23.931,17.396,20.485,17.934,17.038,18.471z"/><path fill="#fff" d="M21.86,9.775c-1.101,0.401-2.203,0.801-3.304,1.202c1.507,0.132,3.015,0.264,4.522,0.395	c0.48,0.796,0.959,1.592,1.439,2.387c0.295-0.722,0.59-1.444,0.885-2.166c1.286-0.1,2.572-0.2,3.858-0.3	c-0.997-0.419-1.994-0.839-2.991-1.259c0.254-0.608,0.508-1.216,0.762-1.825c-0.97,0.29-1.939,0.58-2.909,0.87	c-1.07-0.422-2.14-0.843-3.21-1.265C21.228,8.468,21.544,9.122,21.86,9.775z"/><path fill="#b71c1c" d="M27.267,14.619c2.271-0.906,4.543-1.813,6.814-2.719c1.962,0.834,3.924,1.668,5.886,2.502	c-2.202,0.876-4.403,1.752-6.605,2.629C31.331,16.226,29.299,15.423,27.267,14.619z"/><path fill="#a01c1c" d="M34.082,11.963c-0.005,1.596-0.01,3.191-0.015,4.787c1.967-0.783,3.934-1.565,5.901-2.348	C38.006,13.589,36.044,12.776,34.082,11.963z"/></svg>} href="https://www.aptible.com/docs/redis" />

  <Card title="SFTP" icon="file" href="https://www.aptible.com/docs/sftp" />

  <Card title="See all" icon="grid" href="https://www.aptible.com/docs/core-concepts/managed-databases/supported-databases/overview" />
</CardGroup>

# FAQ

<Accordion title="How do I provision a Database?">
  A Database can be provisioned in three ways on Aptible:

  * Within the Aptible Dashboard by
    * Selecting an existing [Environment](/docs/core-concepts/architecture/environments)
    * Selecting the **Databases** tab
    * Selecting **Create Database**
      * Note: STFP Databases cannot be provisioned via the Aptible Dashboard
      <Frame>
        <img alt="" />
      </Frame>
  * Using the [`aptible db:create`](/docs/reference/aptible-cli/cli-commands/cli-db-create) command
  * Using the Aptible [Terraform Provider](https://registry.terraform.io/providers/aptible/aptible/latest/docs)

  <Note>Database handles cannot start with `internal-` or `sg-` prefixes. Refer to [Managing Databases](/docs/core-concepts/managed-databases/managing-databases/overview) for more information about naming restrictions.</Note>
</Accordion>


# CouchDB
Source: https://www.aptible.com/docs/core-concepts/managed-databases/supported-databases/couchdb

Learn about running secure, Managed CouchDB Databases on Aptible

# Available Versions

<Warning>
  As of October 31, 2024, CouchDB is no longer offered on Aptible.
</Warning>

# Logging in to the CouchDB interface (Fauxton)

To maximize security, Aptible enables authentication in CouchDB, and requires valid users. While this is unquestionably a security best practice, a side effect of requiring authentication in CouchDB is that you can't access the management interface.

Indeed, if you navigate to the management interface on a CouchDB Database where authentication is enabled, you won't be served login form... because any request, including one for the login form, requires authentication! (more on the [CouchDB Blog](https://blog.couchdb.org/2018/02/03/couchdb-authentication-without-server-side-code/)).

That said, you can easily work around this. Here's how. When you access your CouchDB Database (either through a [Database Endpoint](/docs/core-concepts/managed-databases/connecting-databases/database-endpoints) or through a [Database Tunnel](/docs/core-concepts/managed-databases/connecting-databases/database-tunnels)), open your browser's console, and run the following code. Make sure to replace `USERNAME` and `PASSWORD` on the last line with the actual username and password from your [Database Credentials](/docs/core-concepts/managed-databases/connecting-databases/database-credentials).

This code will log you in, then redirect you to Fauxton, the CouchDB management interface.

```javascript theme={null}
(function (name, password) {
  // Don't use a relative URL in fetch: if the user accessed the page by
  // setting a username and password in the URL, that would fail (in fact, it
  // will break Fauxton as well).
  var rootUrl = window.location.href.split("/").slice(0, 3).join("/");
  var basic = btoa(`${name}:${password}`);

  window
    .fetch(rootUrl + "/_session", {
      method: "POST",
      credentials: "include",
      headers: {
        "Content-Type": "application/json",
        Authorization: `Basic ${basic}`,
      },
      body: JSON.stringify({ name, password }),
    })
    .then((r) => {
      if (r.status === 200) {
        return (window.location.href = rootUrl + "/_utils/");
      }
      return r.text().then((t) => {
        throw new Error(t);
      });
    })
    .catch((e) => {
      console.log(`login failed: ${e}`);
    });
})("USERNAME", "PASSWORD");
```

# Configuration

CouchDB Databases can be configured with the [CouchDB HTTP API](http://docs.couchdb.org/en/stable/config/intro.html#setting-parameters-via-the-http-api). Changes made this way will persist across Database restarts.

# Connection Security

Aptible CouchDB Databases support connections via the following protocol:

* For CouchDB version 2.1: `TLSv1.2`


# Elasticsearch
Source: https://www.aptible.com/docs/core-concepts/managed-databases/supported-databases/elasticsearch

Learn about running secure, Managed Elasticsearch Databases on Aptible

# Available Versions

The following versions of [Elasticsearch](https://www.elastic.co/elasticsearch) are currently available:

| Version |   Status  | End-Of-Life Date | Deprecation Date |
| :-----: | :-------: | :--------------: | :--------------: |
|   8.19  | Available |     Jul 2027     |        N/A       |
|   9.2   | Available |        N/A       |        N/A       |
|   9.3   | Available |        N/A       |        N/A       |
|   9.4   | Available |        N/A       |        N/A       |

<Note>For databases on EOL versions, Aptible will prevent new databases from being provisioned and mark existing database as `DEPRECATED` on the deprecation date listed above. While existing databases will not be affected, we recommend end-of-life databases to be [upgraded](https://www.aptible.com/docs/core-concepts/managed-databases/managing-databases/database-upgrade-methods#database-upgrades). Restoring a database from a backup will provision a new database that matches the version associated with the backup, even if that version is EOL or Deprecated. The latest version offered on Aptible will always be available for provisioning, regardless of end-of-life date.</Note>

# Connecting to Elasticsearch

**For Elasticsearch 8.0 or later:**
Elasticsearch is accessible over HTTPS, with Elasticsearch's native authentication mechanism.

The `aptible` user provided by the [Database Credentials](/docs/core-concepts/managed-databases/connecting-databases/database-credentials) is the only user available by default and is configured with the [Elasticsearch Role](https://www.elastic.co/guide/en/elasticsearch/reference/current/built-in-roles.html) of `superuser`. You may [manage the password](https://www.elastic.co/guide/en/elasticsearch/reference/7.8/security-api-change-password.html) of any [Elasticsearch Built-in user](https://www.elastic.co/guide/en/elasticsearch/reference/current/built-in-users.html) if you wish and otherwise manage all aspects of user creation and permissions, with the exception of the `aptible` user.

<Info>Elasticsearch Databases deployed on Aptible use a valid certificate for their host, so you're encouraged to verify the certificate when connecting.</Info>

## Subscription Features

For Elasticsearch 8.0 or later:
Formerly referred to as X-pack features, your [Elastic Stack subscription](https://www.elastic.co/subscriptions) will determine the features available in your Aptible Elasticsearch Database. By default, you will have the "Basic" features. If you purchase a license from Elastic, you may [update your license](https://www.elastic.co/guide/en/kibana/current/managing-licenses.html#update-license) at any time.

# Plugins

Some Elasticsearch plugins may be installed by request. Contact [Aptible Support](https://app.aptible.com/support) if you need a particular plugin.

# Configuration

Elasticsearch Databases can be configured with Elasticsearch's [Cluster Update Settings API](https://www.elastic.co/guide/en/elasticsearch/reference/current/cluster-update-settings.html). Changes made to persistent settings will persist across Database restarts.

Aptible will automatically set the JVM heap size to 50% of the container's memory allocation, per [Elastic's recommendation](https://www.elastic.co/guide/en/elasticsearch/reference/current/heap-size.html#heap-size).

## Kibana

For Elasticsearch 8.0 or later, you can easily deploy [Elastic's official Kibana image](https://hub.docker.com/_/kibana) as an App on Aptible.

<Card title="How to set up Kibana on Aptible" icon="book-open-reader" href="https://www.aptible.com/docs/running-kibana">
  Read the guide
</Card>

## Log Rotation

For Elasticsearch 8.0 or later: if you're using Elasticsearch to hold log data, you may need to periodically create new log indexes. By default, Logstash and our [Log Drains](/docs/core-concepts/observability/logs/log-drains/overview) will create new indexes daily. As the indexes accumulate, they will require more disk space and more RAM. Elasticsearch allocates RAM on a per-index basis, and letting your logs retention grow unchecked will likely lead to fatal issues when the Database runs out of RAM or disk space.

To avoid this, we recommend using a combination of Elasticsearch's native features to ensure you don't accumulate too many open indexes:

* [Index Lifecycle Management](https://www.elastic.co/guide/en/elasticsearch/reference/current/index-lifecycle-management.html) can be configured to delete indexes over a certain age
* [Snapshot Lifecycle Management](https://www.elastic.co/guide/en/elasticsearch/reference/current/snapshot-lifecycle-management.html) can be configured to back up indexes on a schedule, for example, to S3
* The Elasticsearch [S3 Repository Plugin](https://www.elastic.co/guide/en/elasticsearch/plugins/current/repository-s3.html), which is installed by default

<Card title="How to set up Elasticsearch Log Rotation" icon="book-open-reader" href="https://www.aptible.com/docs/elasticsearch-log-rotation">
  Read the guide
</Card>

# Connection Security

Aptible Elasticsearch Databases support connections via the following protocols:

* For Elasticsearch versions 8.X and 9.X: `TLSv1.2` , `TLSv1.3`


# InfluxDB
Source: https://www.aptible.com/docs/core-concepts/managed-databases/supported-databases/influxdb

Learn about running secure, Managed InfluxDB Databases on Aptible

# Available Versions

The following versions of [InfluxDB](https://www.influxdata.com/) are currently available:

| Version |   Status  | End-Of-Life Date | Deprecation Date |
| :-----: | :-------: | :--------------: | :--------------: |
|   1.11  | Available |        N/A       |        N/A       |
|   1.12  | Available |        N/A       |        N/A       |
|   2.7   | Available |        N/A       |        N/A       |

<Note>For databases on EOL versions, Aptible will prevent new databases from being provisioned and mark existing database as `DEPRECATED` on the deprecation date listed above. While existing databases will not be affected, we recommend end-of-life databases to be [upgraded](https://www.aptible.com/docs/core-concepts/managed-databases/managing-databases/database-upgrade-methods#database-upgrades). Restoring a database from a backup will provision a new database that matches the version associated with the backup, even if that version is EOL or Deprecated. The latest version offered on Aptible will always be available for provisioning, regardless of end-of-life date.</Note>

# Accessing data in InfluxDB using Grafana

[Grafana](https://grafana.com) is a great visualization and monitoring tool to use with InfluxDB. For detailed instructions on deploying Grafana to Aptible, follow this tutorial: [Deploying Grafana on Aptible](/docs/how-to-guides/observability-guides/deploy-use-grafana).

# Configuration

Contact [Aptible Support](/docs/how-to-guides/troubleshooting/aptible-support) if you need to change the configuration of an InfluxDB database on Aptible.

# Connection Security

Aptible InfluxDB Databases support connections via the following protocols:

* For InfluxDB version 1.4, 1.7, and 1.8: `TLSv1.0`, `TLSv1.1`, `TLSv1.2`

# Clustering

Clustering is not available for InfluxDB databases since this feature is not available in InfluxDB's open-source offering.


# MongoDB
Source: https://www.aptible.com/docs/core-concepts/managed-databases/supported-databases/mongodb

Learn about running secure, Managed MongoDB Databases on Aptible

## Available Versions

<Warning> Due to MongoDB licensing changes, newer versions of MongoDB will no longer be available on Aptible. </Warning>

The following versions of [MongoDB](https://www.mongodb.com/) are currently available:

| Version |   Status  | End-Of-Life Date | Deprecation Date |
| :-----: | :-------: | :--------------: | :--------------: |
|   4.0   | Available |        N/A       |        N/A       |

<Note>For databases on EOL versions, Aptible will prevent new databases from being provisioned and mark existing database as `DEPRECATED` on the deprecation date listed above. While existing databases will not be affected, we recommend end-of-life databases to be [upgraded](https://www.aptible.com/docs/core-concepts/managed-databases/managing-databases/database-upgrade-methods#database-upgrades). Restoring a database from a backup will provision a new database that matches the version associated with the backup, even if that version is EOL or Deprecated. The latest version offered on Aptible will always be available for provisioning, regardless of end-of-life date.</Note>

# Connecting to MongoDB

Aptible MongoDB [Databases](/docs/core-concepts/managed-databases/overview) require authentication and SSL to connect.

<Tip> MongoDB databases use a valid certificate for their host, so you're encouraged to verify the certificate when connecting.</Tip>

## Connecting to the `admin` database

There are two MongoDB databases you might want to connect to:

* The `admin` database.
* The `db` database created by Aptible automatically.

The username (`aptible`) and password for both databases are the same. However, the users in MongoDB are different (i.e. there is a `aptible` user in the `admin` database, and a separate `aptible` user in the `db` database, which simply happens to have the same password).

This means that if you'd like to connect to the `admin` database, you need to make sure to select that one as your authentication database when connecting: connecting to `db` and running `use admin` will **not** work.

# Clustering

Replica set [clustering](/docs/core-concepts/managed-databases/managing-databases/replication-clustering) is available for MongoDB. Replicas can be created using the [`aptible db:replicate`](/docs/reference/aptible-cli/cli-commands/cli-db-replicate) command.

## Failover

MongoDB replica sets will automatically failover between members. In order to do so effectively, MongoDB recommends replica sets have a minimum of [three members](https://docs.mongodb.com/v4.2/core/replica-set-members/). This can be done by creating two Aptible replicas of the same primary Database.

The [connection URI](https://docs.mongodb.com/v4.2/reference/connection-string/) you provide your Apps with must contain the hostnames and ports of all members in the replica set. MongoDB clients will attempt each host until it's able to reach the replica set. With a single host, if that host is unavailable, the App will not be able to reach the replica set. The hostname and port of each member can be found in the [Database's Credentials](/docs/core-concepts/managed-databases/connecting-databases/database-credentials), and the combined connection URI will look something like this for a three-member replica set:

```
mongodb://username:password@host1.aptible.in:27017,host2.aptible.in:27018,host3.aptible.in:27019/db
```

# Data Integrity and Durability

On Aptible, MongoDB is configured with default settings for journaling. For MongoDB 3.x instances, this means [journaling](https://docs.mongodb.com/manual/core/journaling/) is enabled. If you use the appropriate write concern (`j=1`) when writing to MongoDB, you are guaranteed that committed transactions were written to disk.

# Configuration

Configuration of MongoDB command line options is not supported on Aptible.

MongoDB Databases on Aptible autotune their Wired Tiger cache size based on the size of their Container, based upon [Mongo's recommendation](https://docs.mongodb.com/manual/faq/storage/#to-what-size-should-i-set-the-wiredtiger-internal-cache-).

# Connection Security

Aptible MongoDB Databases support connections via the following protocols:

* For Mongo versions 2.6, 3.4, and 3.6: `TLSv1.0`, `TLSv1.1`, `TLSv1.2`
* For Mongo version 4.0: `TLSv1.1`, `TLSv1.2`


# MySQL
Source: https://www.aptible.com/docs/core-concepts/managed-databases/supported-databases/mysql

Learn about running secure, Managed MySQL Databases on Aptible

# Available Versions

The following versions of [MySQL](https://www.mysql.com/) are currently available:

| Version |   Status  | End-Of-Life Date | Deprecation Date |
| :-----: | :-------: | :--------------: | :--------------: |
|   8.0   | Available |    April 2026    |    August 2026   |
|   8.4   | Available |    April 2029    |    August 2029   |

MySQL releases LTS versions on a biyearly cadence and fully end-of-lifes (EOL) major versions after 8 years of extended support.

<Note>For databases on EOL versions, Aptible will prevent new databases from being provisioned and mark existing database as `DEPRECATED` on the deprecation date listed above. While existing databases will not be affected, we recommend end-of-life databases to be [upgraded](https://www.aptible.com/docs/core-concepts/managed-databases/managing-databases/database-upgrade-methods#database-upgrades). Restoring a database from a backup will provision a new database that matches the version associated with the backup, even if that version is EOL or Deprecated. The latest version offered on Aptible will always be available for provisioning, regardless of end-of-life date.</Note>

## Connecting with SSL

If you get the following error, you're probably not connecting over SSL:

```
ERROR 1045 (28000): Access denied for user 'aptible'@'ip-[IP_ADDRESS].ec2.internal' (using password: YES)
```

Some tools may require additional configuration to connect with SSL to MySQL:

* When connecting via the `mysql` command line client, add this option: `--ssl-cipher=DHE-RSA-AES256-SHA`.
* When connecting via JetBrains DataGrip (through [`aptible db:tunnel`](/docs/reference/aptible-cli/cli-commands/cli-db-tunnel)), you'll need to set `useSSL` to `true` and `verifyServerCertificate` to `false` in the *Advanced* settings tab for the data source.

Most MySQL clients will *not* attempt verification of the server certificate by default; please consult your client's documentation to enable `verify-identity`, or your client's equivalent option. The relevant documentation for the MySQL command line utility is [here](https://dev.mysql.com/doc/refman/8.0/en/using-encrypted-connections.html#using-encrypted-connections-client-side-configuration).

By default, MySQL Databases on Aptible use a server certificate signed by Aptible for SSL / TLS termination. Databases that have been running since prior to Jan 15th, 2021, will only have a self-signed certificate. See [Database Encryption in Transit](/docs/core-concepts/managed-databases/managing-databases/database-encryption/database-encryption-in-transit#self-signed-certificates) for more details.

## Connecting without SSL

<Warning>Never transmit sensitive or regulated information without SSL. Connecting without SSL should only be done for troubleshooting or debugging.</Warning>

For debugging purposes, you can connect to MySQL without SSL using the `aptible-nossl` user. As the name implies, this user does not require SSL to connect.

## Connecting as `root`

If needed, you can connect as `root` to your MySQL database. The password for `root` is the same as that of the `aptible` user.

# Creating More Databases

Aptible provides you with full access to a MySQL instance. If you'd like to add more databases, you can do so by [Connecting as `root`](/docs/core-concepts/managed-databases/supported-databases/mysql#connecting-as-root), then using SQL to create the database:

```sql theme={null}
/* Substitute NAME for the actual name you'd like to use */
CREATE DATABASE NAME;
GRANT ALL ON NAME.* to 'aptible'@'%';
```

# Replication

Source-replica [replication](/docs/core-concepts/managed-databases/managing-databases/replication-clustering) is available for MySQL. Replicas can be created using the [`aptible db:replicate`](/docs/reference/aptible-cli/cli-commands/cli-db-replicate) command.

## Failover

MySQL replicas can accept writes without being promoted. However, it should still be promoted to stop following the source Database so that it doesn't encounter issues when the source Database becomes available again. To do so, run the following commands on the Database:

1. `STOP REPLICA IO_THREAD`
2. Run `SHOW PROCESSLIST` until you see `Has read all relay log` in the output.
3. `STOP REPLICA`
4. `RESET MASTER`

After the replica has been promoted, you should update your [Apps](/docs/core-concepts/apps/overview) to use the promoted replica as the primary Database. Once you start using the replica, you should not go back to using the original primary Database. Instead, continue using the promoted replica and create a new replica off it it.

Aptible maintains a link between replicas and their source Database to ensure the source Database cannot be deleted before the replica. To deprovision the source Database after you've failed over to a promoted replica, users with the appropriate [roles and permissions](/docs/core-concepts/security-compliance/access-permissions#full-permission-type-matrix) can unlink the replica from the source Database. Navigate to the replica's settings page to complete the unlinking process. See the [Deprovisioning a Database documentation ](/docs/core-concepts/managed-databases/managing-databases/overview#deprovisioning-databases)for considerations when deprovisioning a Database.

# Data Integrity and Durability

On Aptible, [binary logging](https://dev.mysql.com/doc/refman/8.4/en/binary-log.html) is enabled (i.e., MySQL is configured with `sync-binlog = 1`). Committed transactions are therefore guaranteed to be written to disk.

# Configuration

We strongly recommend against relying only on `SET GLOBAL` with Aptible MySQL Databases.

Any configuration parameters added using `SET GLOBAL` will be discarded if your Database is restarted (e.g. as a result of exceeding [Memory Limits](/docs/core-concepts/scaling/memory-limits), the underlying hardware crashing, or simply as a result of a [Database Scaling](/docs/core-concepts/scaling/database-scaling) operation). In this scenario, unless your App automatically detects this condition and uses `SET GLOBAL` again, your custom configuration will no longer be present.

However, Aptible Support can accommodate reasonable configuration changes so that they can be persisted across restarts (by adding them to a configuration file). If you're contemplating using `SET GLOBAL` (for enabling the [General Query Log](https://dev.mysql.com/doc/refman/8.4/en/query-log.html) as an example), please get in touch with [Aptible Support](/docs/how-to-guides/troubleshooting/aptible-support) to apply the setting persistently.

MySQL Databases on Aptible autotune their buffer pool and chunk size based on the size of their container to improve performance. The `innodb_buffer_pool_size` setting will be set to half of the container memory, and `innodb_buffer_pool_chunk_size` and `innodb_buffer_pool_instances` will be set to approriate values.  You can view all buffer pool settings, including these autotuned values, with the following query: `SHOW VARIABLES LIKE 'innodb_buffer_pool_%'`.

# Connection Security

Aptible MySQL Databases support connections via the following protocols:

* For MySQL version 8.0 and 8.4: `TLSv1.2`, `TLSv1.3`


# PostgreSQL
Source: https://www.aptible.com/docs/core-concepts/managed-databases/supported-databases/postgresql

Learn about running secure, Managed PostgreSQL Databases on Aptible

# Available Versions

The following versions of [PostgreSQL](https://www.postgresql.org/) are currently available:

| Version |   Status  | End-Of-Life Date | Deprecation Date |
| :-----: | :-------: | :--------------: | :--------------: |
|    14   | Available |   November 2026  |   February 2027  |
|    15   | Available |   November 2027  |   February 2028  |
|    16   | Available |   November 2028  |   February 2029  |
|    17   | Available |   November 2029  |   February 2030  |
|    18   | Available |   November 2030  |   February 2031  |

<Info>PostgreSQL releases new major versions annually, and supports major versions for 5 years before it is considered end-of-life and no longer maintained.</Info>

<Note>For databases on EOL versions, Aptible will prevent new databases from being provisioned and mark existing database as `DEPRECATED` on the deprecation date listed above. While existing databases will not be affected, we recommend end-of-life databases to be [upgraded](https://www.aptible.com/docs/core-concepts/managed-databases/managing-databases/database-upgrade-methods#database-upgrades). Restoring a database from a backup will provision a new database that matches the version associated with the backup, even if that version is EOL or Deprecated. The latest version offered on Aptible will always be available for provisioning, regardless of end-of-life date.</Note>

# Connecting to PostgreSQL

Aptible PostgreSQL [Databases](/docs/core-concepts/managed-databases/overview) require authentication and SSL to connect.

## Connecting with SSL

Most PostgreSQL clients will attempt connection over SSL by default. If yours doesn't, try appending `?ssl=true` to your connection URL, or review your client's documentation.

Most PostgreSQL clients will *not* attempt verification of the server certificate by default, please consult your client's documentation to enable `verify-full`, or your client's equivalent option. The relevant documentation for libpq is [here](https://www.postgresql.org/docs/current/libpq-ssl.html#LIBQ-SSL-CERTIFICATES).

By default, PostgreSQL Databases on Aptible use a server certificate signed by Aptible for SSL / TLS termination. Databases that have been running since prior to Jan 15th, 2021 will only have a self-signed certificate. See [Database Encryption in Transit](/docs/core-concepts/managed-databases/managing-databases/database-encryption/database-encryption-in-transit#self-signed-certificates) for more details.

# Extensions

The listed extensions alongside those listed in [PostgreSQL's documentation here](https://www.postgresql.org/docs/current/contrib.html) are available for use.

| Extension  | Available in versions |
| ---------- | --------------------- |
| pg\_cron   | 15 - 18               |
| pgaudit    | 14 - 18               |
| pglogical  | 14 - 18               |
| pg\_repack | 14 - 18               |
| pgvector   | 14 - 18               |
| postgis    | 14 - 18               |
| wal2json   | 14 - 18               |

If you require a particular PostgreSQL extension, contact [Aptible Support](/docs/how-to-guides/troubleshooting/aptible-support) to identify whether it's a good fit for Aptible.

<Tip>
  To replicate PostgreSQL changes into Google BigQuery, see [Replicate PostgreSQL to BigQuery with Datastream](/docs/how-to-guides/database-guides/replicate-postgresql-to-bigquery-datastream).
</Tip>

<Accordion title="pg_cron">
  [pg\_cron](https://github.com/citusdata/pg_cron) lets you schedule recurring database jobs using standard cron syntax. Unlike other extensions, pg\_cron requires additional configuration before you can enable it.

  ### Enabling pg\_cron

  First, add pg\_cron to `shared_preload_libraries`:

  ```sql theme={null}
  ALTER SYSTEM SET shared_preload_libraries = pg_stat_statements, pglogical, pg_cron;
  ```

  Restart your database using the Aptible CLI or Dashboard for the change to take effect.

  Once the database has restarted, connect to the `postgres` database and configure pg\_cron and max worker settings:

  ```sql theme={null}
  ALTER SYSTEM SET cron.database_name = 'postgres';
  ALTER SYSTEM SET cron.use_background_workers = on;
  ALTER SYSTEM SET cron.max_running_jobs = 5;
  ALTER SYSTEM SET max_worker_processes = 16;
  ```

  <Note>On Aptible, pg\_cron must use background workers over localhost connections. The `cron.max_running_jobs` and `max_worker_processes` values above should be adjusted to account for the number of concurrently running cron jobs </Note>

  Restart the database again, then create the extension:

  ```sql theme={null}
  CREATE EXTENSION pg_cron;
  ```

  <Note>The pg\_cron extension must be created in the database `cron.database_name` is set to. However, jobs scheduled with pg\_cron can run queries against any database on the same PostgreSQL instance.</Note>

  ### Scheduling jobs

  Once enabled, schedule jobs using `cron.schedule`:

  ```sql theme={null}
  SELECT cron.schedule('nightly-vacuum', '0 3 * * *', 'VACUUM ANALYZE my_table');
  ```

  To schedule a job in a specific database:

  ```sql theme={null}
  SELECT cron.schedule_in_database('nightly-vacuum', '03 * * *', 'VACUUM ANALYZE my_table', '$DATABASE');
  ```

  To view scheduled jobs:

  ```sql theme={null}
  SELECT * FROM cron.job;
  ```

  To remove a scheduled job:

  ```sql theme={null}
  SELECT cron.unschedule('nightly-vacuum');
  ```
</Accordion>

<Accordion title="pgaudit">
  [pgaudit](https://github.com/pgaudit/pgaudit) provides detailed session and object audit logging for PostgreSQL, helping you meet compliance requirements by recording which statements were executed against your database.

  ### Enabling pgaudit

  First, add pgaudit to `shared_preload_libraries`:

  ```sql theme={null}
  ALTER SYSTEM SET shared_preload_libraries = pg_stat_statements, pglogical, pgaudit;
  ```

  Restart your database using the Aptible CLI or Dashboard for the change to take effect.

  Once the database has restarted, create the extension:

  ```sql theme={null}
  CREATE EXTENSION pgaudit;
  ```

  ### Configuring audit logging

  pgaudit supports two modes of logging: **session** (logs all statements from a session) and **object** (logs statements that affect specific relations).

  To enable session audit logging for all DML statements (reads, writes, deletes):

  ```sql theme={null}
  ALTER SYSTEM SET pgaudit.log = 'read, write';
  ```

  Restart the database for the change to take effect. You can also set `pgaudit.log` at the role or session level without a restart:

  ```sql theme={null}
  ALTER ROLE my_app_user SET pgaudit.log = 'read, write';
  ```

  Available log classes include:

  | Class      | Description                                     |
  | ---------- | ----------------------------------------------- |
  | `read`     | SELECT and COPY when source is a relation       |
  | `write`    | INSERT, UPDATE, DELETE, TRUNCATE, COPY (target) |
  | `function` | Function calls and DO blocks                    |
  | `role`     | GRANT, REVOKE, CREATE/ALTER/DROP ROLE           |
  | `ddl`      | All DDL not covered by ROLE class               |
  | `misc`     | Miscellaneous (e.g., DISCARD, FETCH, VACUUM)    |
  | `all`      | All of the above                                |

  ### Object audit logging

  For finer-grained control, assign an auditor role and grant it access only to the tables you want to audit:

  ```sql theme={null}
  CREATE ROLE auditor NOLOGIN;
  ALTER SYSTEM SET pgaudit.role = 'auditor';
  GRANT SELECT ON my_sensitive_table TO auditor;
  ```

  After restarting, any SELECT on `my_sensitive_table` will be logged regardless of the `pgaudit.log` setting.

  ### Viewing audit logs

  pgaudit writes to the standard PostgreSQL log. On Aptible, these logs are available through the [Log Drains](/docs/core-concepts/observability/logs/log-drains/overview) configured for your environment.
</Accordion>

<Accordion title="pg_repack">
  [pg\_repack](https://github.com/reorg/pg_repack) lets you remove bloat from tables and indexes without holding exclusive locks during the process.

  ### Enabling pg\_repack

  Create the extension in the database you want to repack:

  ```sql theme={null}
  CREATE EXTENSION pg_repack;
  ```

  ### Repacking tables

  pg\_repack is run using its CLI utility. Connect to your database through a database tunnel and run:

  ```bash theme={null}
  pg_repack -h $HOST -p $PORT -U $USER -d $DATABASE --table my_table
  ```

  To repack all tables in a database:

  ```bash theme={null}
  pg_repack -h $HOST -p $PORT -U $USER -d $DATABASE
  ```

  ### Common options

  | Option             | Description                                        |
  | ------------------ | -------------------------------------------------- |
  | `--table TABLE`    | Repack a specific table                            |
  | `--only-indexes`   | Repack only indexes on the specified table         |
  | `--index INDEX`    | Repack a specific index                            |
  | `--no-order`       | Repack without reordering by cluster index         |
  | `--wait-timeout N` | Seconds to wait for lock acquisition (default: 60) |

  <Note>pg\_repack requires free disk space roughly equal to the size of the table being repacked. Monitor your disk usage before running it on large tables.</Note>
</Accordion>

<Accordion title="pgvector">
  [pgvector](https://github.com/pgvector/pgvector) adds vector similarity search to PostgreSQL, enabling you to store embeddings and perform nearest-neighbor queries directly in your database.

  ### Enabling pgvector

  Create the extension:

  ```sql theme={null}
  CREATE EXTENSION vector;
  ```

  ### Storing vectors

  Add a vector column to your table by specifying the number of dimensions:

  ```sql theme={null}
  CREATE TABLE documents (
    id BIGSERIAL PRIMARY KEY,
    content TEXT,
    embedding VECTOR(1536)
  );
  ```

  Insert vector data as an array-like string:

  ```sql theme={null}
  INSERT INTO documents (content, embedding)
  VALUES ('example document', '[0.1, 0.2, 0.3, ...]');
  ```

  ### Querying vectors

  Find the 5 nearest neighbors using cosine distance (`<=>`):

  ```sql theme={null}
  SELECT id, content, embedding <=> '[0.1, 0.2, 0.3, ...]' AS distance
  FROM documents
  ORDER BY embedding <=> '[0.1, 0.2, 0.3, ...]'
  LIMIT 5;
  ```

  Other supported distance operators:

  | Operator | Distance metric          |
  | -------- | ------------------------ |
  | `<->`    | L2 (Euclidean)           |
  | `<=>`    | Cosine                   |
  | `<#>`    | Inner product (negative) |

  ### Indexing for performance

  For large datasets, create an index to speed up similarity searches. pgvector supports two index types:

  **HNSW** (recommended for most use cases):

  ```sql theme={null}
  CREATE INDEX ON documents
  USING hnsw (embedding vector_cosine_ops);
  ```

  **IVFFlat** (faster to build, good for very large datasets):

  ```sql theme={null}
  CREATE INDEX ON documents
  USING ivfflat (embedding vector_cosine_ops)
  WITH (lists = 100);
  ```

  <Note>Choose the operator class that matches your distance metric: `vector_cosine_ops` for cosine, `vector_l2_ops` for L2, or `vector_ip_ops` for inner product.</Note>
</Accordion>

# Replication

Primary-standby [replication](/docs/core-concepts/managed-databases/managing-databases/replication-clustering) is available for PostgreSQL. Replicas can be created using the [`aptible db:replicate`](/docs/reference/aptible-cli/cli-commands/cli-db-replicate) command.

## Failover

PostgreSQL replicas can be manually promoted to stop following the primary and start accepting writes. To do so, run one of the following commands depending on your Database's version:

PostgreSQL 12 and higher

```
SELECT pg_promote();
```

PostgreSQL 11 and lower

```
COPY (SELECT 'fast') TO '/var/db/pgsql.trigger';
```

After the replica has been promoted, you should update your [Apps](/docs/core-concepts/apps/overview) to use the promoted replica as the primary Database. Once you start using the replica, you should not go back to using the original primary Database. Instead, continue using the promoted replica and create a new replica off of it.

Aptible maintains a link between replicas and their source Database to ensure the source Database cannot be deleted before the replica. To deprovision the source Database after you've failed over to a promoted replica, users with the appropriate [roles and permissions](/docs/core-concepts/security-compliance/access-permissions#full-permission-type-matrix) can unlink the replica from the source Database. Navigate to the replica's settings page to complete the unlinking process. See the [Deprovisioning a Database](/docs/how-to-guides/platform-guides/deprovision-resources) documentation for considerations when deprovisioning a Database.

# Data Integrity and Durability

On Aptible, PostgreSQL is configured with default settings for [write-ahead logging](https://www.postgresql.org/docs/current/static/wal-intro.html). Committed transactions are therefore guaranteed to be written to disk.

# Point-in-time Recovery

Point-in-time Recovery (PITR) is available for PostgreSQL 13 and newer. PITR lets you restore your database to any specific moment in time, protecting against accidental data deletions, corruptions, or other errors.

Aptible automatically enables PITR for new PostgreSQL 13+ databases if your Environment's backup retention policy has at least 1 day of recovery data retention configured.

For more details on configuring and using PITR, see [Point-in-Time Recovery (PITR)](/docs/core-concepts/managed-databases/managing-databases/point-in-time-recovery).

# Configuration

A PostgreSQL database's [`pg_settings`](https://www.postgresql.org/docs/current/view-pg-settings.html) can be changed with [`ALTER SYSTEM`](https://www.postgresql.org/docs/current/sql-altersystem.html). Changes made this way are written to disk and will persist across database restarts.

PostgreSQL databases on Aptible autotune the size of their caches and working memory based on the size of their container in order to improve performance.

The following settings are autotuned:

* `shared_buffers`

* `effective_cache_size`

* `work_mem`

* `maintenance_work_mem`

* `checkpoint_completion_target`

* `default_statistics_target`

Modifying these settings is not recommended as the setting will no longer scale with the size of the database's container.

## Autovacuum

Postgres [Autovacuum](https://www.postgresql.org/docs/current/routine-vacuuming.html#AUTOVACUUM) is enabled by default on all supported Aptible PostgreSQL managed databases. Autovacuum is configured with
default settings related to [Vacuum](https://www.postgresql.org/docs/current/sql-vacuum.html), which can be inspected with:

```
SELECT * FROM pg_settings WHERE name LIKE '%autovacuum%;'
```

The settings associated with autovacuum can be adjusted with [ALTER SYSTEM](https://www.postgresql.org/docs/current/sql-altersystem.html)

# Connection Security

Aptible PostgreSQL Databases support connections via the following protocols:

* For PostgreSQL version 14: `TLSv1.2`

* For PostgreSQL versions 15, 16, 17, and 18: `TLSv1.2`, `TLSv1.3`


# RabbitMQ
Source: https://www.aptible.com/docs/core-concepts/managed-databases/supported-databases/rabbitmq



# Available Versions

The following versions of RabbitMQ are currently available:

| Version |   Status  | End-Of-Life Date | Deprecation Date |
| :-----: | :-------: | :--------------: | :--------------: |
|   4.1   | Available |        N/A       |        N/A       |
|   4.2   | Available |        N/A       |        N/A       |

<Note>For databases on EOL versions, Aptible will prevent new databases from being provisioned and mark existing database as `DEPRECATED` on the deprecation date listed above. While existing databases will not be affected, we recommend end-of-life databases to be [upgraded](https://www.aptible.com/docs/core-concepts/managed-databases/managing-databases/database-upgrade-methods#database-upgrades). Restoring a database from a backup will provision a new database that matches the version associated with the backup, even if that version is EOL or Deprecated. The latest version offered on Aptible will always be available for provisioning, regardless of end-of-life date.</Note>

# Connecting to RabbitMQ

Aptible RabbitMQ [Databases](/docs/core-concepts/managed-databases/overview) require authentication and SSL to connect.

<Tip>RabbitMQ Databases use a valid certificate for their host, so you’re encouraged to verify the certificate when connecting.</Tip>

# Connecting to the RabbitMQ Management Interface

Aptible RabbitMQ [Databases](/docs/core-concepts/managed-databases/overview) provide access to the management interface.

Typically, you should access the management interface via a [Database Tunnel](/docs/core-concepts/managed-databases/connecting-databases/database-tunnels). For example:

```shell theme={null}
aptible db:tunnel "$DB_HANDLE" --type management
```

# Connecting to RabbitMQ Prometheus

You can create a Database Tunnel to connect to the Prometheus endpoint locally, or use [Prometheus with Grafana](https://www.rabbitmq.com/docs/prometheus) as a monitoring solution.

```shell theme={null}
aptible db:tunnel "$DB_HANDLE" --type prometheus
```

Note that the Prometheus plugin on Aptible is configured with HTTP Authentication, so you will need to provide the username and password to reach the endpoint.

# Modifying RabbitMQ Parameters & Policies

RabbitMQ [parameters](https://www.rabbitmq.com/parameters.html) can be updated via the management API and changes will persist across Database restarts.

The [log level](https://www.rabbitmq.com/logging.html#log-levels) of a RabbitMQ Database can be changed by contacting [Aptible Support](/docs/how-to-guides/troubleshooting/aptible-support), but other [configuration file](https://www.rabbitmq.com/configure.html#configuration-files) values cannot be changed at this time.

# Connection Security

Aptible RabbitMQ Databases support connections via the following protocols:

* For RabbitMQ version 3.13, 4.0: `TLSv1.2`, `TLSv1.3`


# Redis
Source: https://www.aptible.com/docs/core-concepts/managed-databases/supported-databases/redis

Learn about running secure, Managed Redis Databases on Aptible

## Available Versions

The following versions of [Redis](https://redis.io/) are currently available:

| Version |   Status  | End-Of-Life Date | Deprecation Date |
| :-----: | :-------: | :--------------: | :--------------: |
|   6.2   | Available |        N/A       |        N/A       |
|   7.2   | Available |        N/A       |        N/A       |
|   8.2   | Available |        N/A       |        N/A       |
|   8.4   | Available |        N/A       |        N/A       |
|   8.6   | Available |        N/A       |        N/A       |
|   8.8   | Available |        N/A       |        N/A       |

<Info>Redis typically releases new major versions annually with a minor version release 6 months after. The latest major version is fully maintained and supported by Redis, while the previous major version and minor version receive security fixes only. All other versions are considered end-of-life.</Info>

<Note>For databases on EOL versions, Aptible will prevent new databases from being provisioned and mark existing database as `DEPRECATED` on the deprecation date listed above. While existing databases will not be affected, we recommend end-of-life databases to be [upgraded](https://www.aptible.com/docs/core-concepts/managed-databases/managing-databases/database-upgrade-methods#database-upgrades). Restoring a database from a backup will provision a new database that matches the version associated with the backup, even if that version is EOL or Deprecated. The latest version offered on Aptible will always be available for provisioning, regardless of end-of-life date.</Note>

# Connecting to Redis

Aptible Redis [Databases](/docs/core-concepts/managed-databases/overview) expose two [Database Credentials](/docs/core-concepts/managed-databases/connecting-databases/database-credentials):

* A `redis` credential. This is for plaintext connections, so you shouldn't use it for sensitive or regulated information.
* A `redis+ssl` credential. This accepts connections over TLS, and it's the one you should use for regulated or sensitive information.

<Tip> The SSL port uses a valid certificate for its host, so you’re encouraged to verify the certificate when connecting.</Tip>

# Replication

Master-replica [replication](/docs/core-concepts/managed-databases/managing-databases/replication-clustering) is available for Redis. Replicas can be created using the [`aptible db:replicate`](/docs/reference/aptible-cli/cli-commands/cli-db-replicate) command.

## Failover

Redis replicas can be manually promoted to stop following the primary and start accepting writes. To do so, run the following command on the Database:

```
REPLICAOF NO ONE
```

After the replica has been promoted, you should update your [Apps](/docs/core-concepts/apps/overview) to use the promoted replica as the primary Database. Once you start using the replica, you should not go back to using the original primary Database. Instead, continue using the promoted replica and create a new replica off of it.

The effects of `REPLICAOF NO ONE` are not persisted to the Database's filesystem, so the next time the Database starts, it will attempt to replicate the source Database again. In order to persist this change, contact [Aptible Support](/docs/how-to-guides/troubleshooting/aptible-support) with the name of the Database and request that it be permanently promoted.

Aptible maintains a link between replicas and their source Database to ensure the source Database cannot be deleted before the replica. To deprovision the source Database after you've failed over to a promoted replica, users with the appropriate [roles and permissions](/docs/core-concepts/security-compliance/access-permissions#full-permission-type-matrix) can unlink the replica from the source database. Navigate to the replica's settings page to complete the unlinking process. See the [Deprovisioning a Database](/docs/how-to-guides/platform-guides/deprovision-resources) documentation for considerations when deprovisioning a Database.

# Data Integrity and Durability

When you provision Redis on Aptible, choose the persistence flavor based on how your application uses Redis:

* Use the default AOF + RDB flavor when Redis stores data that should survive restarts.
* Use an RDB-only flavor when periodic snapshots are enough and you want less disk write activity.
* Use a memory-only flavor when Redis is only a cache and data loss on restart is acceptable.

On Aptible, Redis is configured by default to use both Append-only file (AOF) and RDB persistence. This means your data is stored in two formats on disk. Redis on Aptible uses the every-second fsync policy for AOF, and the following configuration for RDB snapshots:

```
save 900 1
save 300 10
save 60 10000
```

This configuration means Redis performs an RDB backup every 900 seconds at most, every 300 seconds if 10 keys are changed, and every 60 seconds if 10000 keys are changed. Additionally, each time a write operation is performed, it is immediately written to the append-only file and flushed from the kernel to the disk (using fsync) one time every second.

Broadly speaking, Redis is not designed to be a durable data store. We do not recommend using Redis in cases where durability is required.

## RDB-only flavors

If you'd like to use Redis with AOF disabled and RDB persistence enabled, we provide Redis images in this configuration that you can elect to use.

One of the benefits of RDB-only persistence is the fact that for a given database size, the number of I/O operations is bound by the above configuration, whatever the activity on the database is. However, if Redis crashes or runs out of memory between RDB backups, data might be lost.

Note that an RDB snapshot means Redis is writing data to disk and is not the same thing as an Aptible [Database Backup](/docs/core-concepts/managed-databases/managing-databases/database-backups). Aptible Database Backups are snapshots of your Database's disk. In other words: Redis periodically commits data to disk according to the Redis persistence configuration, and Aptible periodically snapshots the disk that contains that data.

These database types are displayed as `RDB-Only Persistence` on the Dashboard.

## Memory-only flavors

If you'd like to use Redis as a memory-only store (i.e., without any persistence), we provide Redis images with AOF and RDB persistence disabled.

If you use one of those (they aren't the default), make sure you understand that **all data in Redis will be lost upon restarting or resizing your memory-only instance or upon your memory-only instance running out of memory.**

If you'd like to use a memory-only flavor, provision it using the [`aptible db:create`](/docs/reference/aptible-cli/cli-commands/cli-db-create) command (substitute `$HANDLE` with your desired handle for this Database). Since the disk will only be used to store configuration files, use the minimum size (with the `--disk-size` parameter as listed below):

```shell theme={null}
aptible db:create \
        --type redis \
        --version 7.0-nordb \
        --disk-size 10 \
        "$HANDLE"
```

These database types are displayed as `NO PERSISTENCE` on the Dashboard.

## Disk Sizing

Choose disk size based on the Redis persistence flavor:

* AOF + RDB: allocate disk space equal to at least 4x the Container memory size to allow room for snapshots and AOF rewrite operations.
* RDB-only: allocate disk space equal to at least 2x the Container memory size.
* Memory-only: use the minimum disk size for the selected Redis version because the disk stores configuration rather than Redis data. For current Redis 7 memory-only flavors, a 10 GB disk is sufficient.

## Specifying a flavor

When creating a Redis database from the Aptible Dashboard, you only have the option of version with both AOF and RDB enabled.

To list available Redis flavors that can be passed to [`aptible db:create`](/docs/reference/aptible-cli/cli-commands/cli-db-create) via the `--version` option, use the [`aptible db:versions`](/docs/reference/aptible-cli/cli-commands/cli-db-versions) command:

* `..-aof` are the AOF + RDB ones.
* `..-nordb` are the memory-only ones.
* The unadorned versions are RDB-Only.

# Configuration

Contact [Aptible Support](/docs/how-to-guides/troubleshooting/aptible-support) if you have a need to change the configuration of a Redis database on Aptible.

# Connection Security

Aptible Redis databases support connections via the following protocols:

* For Redis versions 2.8, 3.0, 3.2, 4.0, and 5.0: `TLSv1.0`, `TLSv1.1`, `TLSv1.2`
* For Redis versions 6.0, 6.2, 7.0, and 7.2: `TLSv1.2`
* For Redis versions 8.0 and newer: `TLSv1.2`, `TLSv1.3`


# SFTP
Source: https://www.aptible.com/docs/core-concepts/managed-databases/supported-databases/sftp



STFP Databases can be provisioned in the following ways:

* In the Dashboard > Environment > Databases > "New Database"  > SFTP
* Using the [`aptible db:create`](/docs/reference/aptible-cli/cli-commands/cli-db-create) command
  * For example: `aptible db:create "$DB_HANDLE" --type sftp`
* Using the [Aptible Terraform Provider](/docs/reference/terraform)

# Usage

The service is designed to run with an initial, password-protected admin user. The credentials for this user can be viewed in the [Database Credentials](/docs/core-concepts/managed-databases/connecting-databases/database-credentials) section of the database page. Additional users can be provisioned anytime by calling add-sftp-user with a username and SSH public key.

<Warning>
  By default, this SFTP service defaults files to be stored in the given users home directory (in the `/home/%u` format). Files in the `/home/%u` directory structure are located on a persistent volume that will be reliably persisted between any reload/restart/scale/maintenance activity of the SFTP instance. However, the initial `aptible` user is a privileged user which can store files elsewhere in the file system, in areas which are on an ephemeral volume which will be lost during any reload/restart/scale/maintenance activity. Please only store SFTP files in the users' home directory structure!
</Warning>

## Connecting and Adding Users

* Run a db:tunnel in one terminal window: `aptible db:tunnel $DB_HANDLE`
* This will give output of a URL containing the host/password/port
* In another terminal window: `ssh -p PORT aptible@localhost.aptible.in` (where PORT is copied from the port provided in the previous step)
* Use the password provided in the previous step
* Once in the shell, you can use the `add-sftp-user` utility to add additional users to the SFTP instance. Please note that additional users added with this utility must use [ssh key authentication](/docs/core-concepts/security-compliance/authentication/ssh-keys), and the public key is provided as an argument to the command.

```
sudo add-sftp-user regular-user "SSH_PUBLIC_KEY"
```

where `SSH_PUBLIC_KEY` would be the ssh public key for the user. To provide a fictional public key (truncated for readability) as an example:

```
sudo add-sftp-user regular-user "ssh-rsa AAAAB3NzaC1yc2EBAQClKswlTG2MO7YO9wENmf user@example.com"
```


# Activity Details
Source: https://www.aptible.com/docs/core-concepts/observability/activity/activity-details

Complete list of all activity event types tracked in Aptible

## Activity Event Types

<Note>
  Depending on your role and when a specific activity type began being recorded, you may not see all activities listed below.

  <sup>1</sup> Requires the Deploy Owner or Account Owner role

  <sup>2</sup> Activity history begins Nov 1, 2025

  <sup>3</sup> Activity history begins Feb 18, 2026

  <sup>4</sup> Activity history begins March 17, 2026

  <sup>5</sup> This activity is logged whenever sensitive data is potentially included in the response

  <sup>6</sup> Activity history begins June 17, 2026
</Note>

### App Activities<Tooltip><sup>2</sup></Tooltip>

* App Configure
* App Deploy
* App Deprovision
* App SSH
* App Rebuild
* App Restart
* App Scan
* Service Scale
* Service Settings Update

### Database Activities<Tooltip><sup>2</sup></Tooltip>

* Database Backup
* Database Clone
* Database Backup Policy Configure
* Database Deprovision
* Database Disable Backups
* Database Enable Backups
* Database Stop
* Database Modify
* Database Point-in-Time Restore
* Database Provision
* Database Reload
* Database Replicate
* Database Replicate (Logical)
* Database Restart
* Database Tunnel
* Database Replica Unlink

### Backup Activities<Tooltip><sup>2</sup></Tooltip>

* Backup Copy
* Backup Purge
* Backup Restore

### Endpoint Activities<Tooltip><sup>2</sup></Tooltip>

* Endpoint Deprovision
* Endpoint Provision
* Endpoint Renew
* Endpoint Update<Tooltip><sup>3</sup></Tooltip>

### Persistent Disk Activities<Tooltip><sup>6</sup></Tooltip>

* Persistent Disk Provisioned
* Persistent Disk Modified
* Persistent Disk Deprovisioned
* Persistent Disk Attached
* Persistent Disk Detached

### Log & Metric Drain Activities<Tooltip><sup>2</sup></Tooltip>

* Log Drain Configure
* Log Drain Deprovision
* Log Drain Provision
* Metric Drain Deprovision
* Metric Drain Provision

### VPN Tunnel Activities<Tooltip><sup>1</sup></Tooltip><Tooltip><sup>2</sup></Tooltip>

* VPN Tunnel Provision
* VPN Tunnel Deprovision

### Sensitive Data Access Activities<Tooltip><sup>4</sup> </Tooltip><Tooltip><sup>5</sup></Tooltip>

* App Logs
* Database Logs
* Operation Logs
* Certificate Show
* Configuration Show
* Database Show
* Database Credentials Show
* Endpoint Show
* Log Drain Show
* Metric Drain Show
* Operation Show
* Settings Show

### User & Authentication Activities<Tooltip><sup>1</sup></Tooltip><Tooltip><sup>3</sup></Tooltip>

* User logged in
* User logged out
* OTP configuration created
* OTP configuration destroyed
* U2F device added
* U2F device removed
* SSO/SAML configuration created
* SSO/SAML configuration destroyed

### Access Control Activities<Tooltip><sup>1</sup></Tooltip><Tooltip><sup>3</sup></Tooltip>

* User Login
* User Logout
* U2F Device Create
* U2F Device Destroy
* OTP Configuration Create
* OTP Configuration Destroy
* Permission Create
* Permission Destroy
* Role Create
* Role Destroy
* Role Update
* SAML Configuration Create
* SAML Configuration Destroy
* SSO Bypass List Update

<Note>
  For users with MFA enabled, you may see an initial "failed" login activity with the reason "2FA not supplied" when the user submits their password. This is expected — once the user successfully completes MFA, the failed attempt is updated to a successful login. Requires CLI version 0.26.2 or later.
</Note>

### Backup Policy Activities<Tooltip><sup>2</sup></Tooltip>

* Environment Configure Backup Policy

### Activity Exports

* Activity Export
* Activity Export Download


# Activity Reports
Source: https://www.aptible.com/docs/core-concepts/observability/activity/activity-reports

Learn about exporting historical activity data from Aptible

<img alt="" />

Activity Reports provide historical data of all operations in a given environment, including operations executed on resources that were later deleted. These reports are generated on a weekly basis for each environment, and they can be accessed for the duration of the environment's existence.

<Info>Activity Reports only include App, Database, Backup, Endpoint, Log & Metric Drain, and VPN Tunnel Activities. User & Authentication, Access Control and Backup Policy Activities are not yet included in these reports.</Info>


# SIEM/Logging Integration
Source: https://www.aptible.com/docs/core-concepts/observability/activity/integrations

Stream Aptible activity events to your SIEM or logging provider

You can stream [Activity](/docs/core-concepts/observability/activity/overview) events from your Aptible organization to a SIEM or logging provider for centralized monitoring, alerting, or other compliance needs.

## Activity Logs Token

Any user can generate a long-lived Activity Logs token in Settings → Tokens. This token provides read-only access to the activity logs that user can already access, plus the organizational metadata required to retrieve them.

For a SIEM integration, we recommend creating a dedicated user and adding them to the [Activity Log Viewer Role](/docs/core-concepts/security-compliance/access-permissions#activity-log-viewer), which grants read-only access to all activity across your organization.

<Frame>
  <img alt="Generate Activity Logs Token" />
</Frame>

The token can be valid for however long you choose, up to a year. You'll need to rotate it in your integration's configuration on that schedule. These integrations can handle interruption, so you won't be permanently missing activity if the token lapses: as soon as you replace an expired token, the integration resumes from its last saved position.

## Supported Providers

Get started by following the setup guide for your provider:

* [**Hosted Elasticsearch (Elastic Cloud)**](/docs/core-concepts/observability/activity/integrations/elastic-cloud) — via the Custom API integration (HTTPJSON input)
* [**Sumo Logic**](/docs/core-concepts/observability/activity/integrations/logging-provider) — via a self-hosted forwarding container

Don't see your provider? [Contact Aptible Support](https://app.aptible.com/support) to discuss your integration needs.


# Hosted Elasticsearch
Source: https://www.aptible.com/docs/core-concepts/observability/activity/integrations/elastic-cloud

Stream Aptible activity events to hosted Elasticsearch

## Elastic Cloud Setup

### Prerequisites

* A hosted Elasticsearch deployment on [Elastic Cloud](https://www.elastic.co/cloud)
* A [long-term activity access token](/docs/core-concepts/security-compliance/access-permissions#activity-log-viewer) (coming soon!)

### Step 1: Identify Your Data Stream

Imported activities will be written to a named Data Stream. If you don't already have one you want to use, we'll assume you'll use one called `aptible_activity`, which will be created automatically during step 3.

### Step 2: Create an Ingest Pipeline

In Kibana, navigate to **<Tooltip>Stack Management</Tooltip> > Ingest Pipelines** and create a new pipeline named `aptible_activity_pipeline` with the following three processors. You can import this JSON when creating it:

```json theme={null}
{
  "processors": [
    {
      "json": {
        "field": "message",
        "target_field": "aptible"
      }
    },
    {
      "date": {
        "formats": ["ISO8601"],
        "field": "aptible.occurred_at",
        "target_field": "@timestamp"
      }
    },
    {
      "set": {
        "field": "_id",
        "value": "aptible_activity_{{aptible.id}}"
      }
    }
  ]
}
```

Each processor serves a specific purpose:

* **`json`** — Parses the raw `message` field into individual fields under `aptible.*` (e.g. `aptible.primary_resource_id`, `aptible.status`, `aptible.summary`), making them searchable and filterable. If you want to discard the original `message` field after parsing, add `"remove_if_successful": true`.
* **`date`** — Sets `@timestamp` to the event's `occurred_at` time so that events are indexed by when they happened, not when they were ingested.
* **`set _id`** — Assigns a predictable document ID based on the Aptible activity ID. This prevents duplicate events if the same activity is fetched more than once.

### Step 3: Set Up the Custom API Integration

In Kibana, navigate to **Integrations** and search for **Custom API**. Add a new **Custom API** integration with the following settings:

#### Basic Settings

| Setting                 | Value                                                                        |
| ----------------------- | ---------------------------------------------------------------------------- |
| **Dataset name**        | `aptible_activity` (the index identified/created in step #1)                 |
| **Ingest Pipeline**     | `aptible_activity_pipeline` (the name of the pipeline created in step #2)    |
| **Request URL**         | `https://activity.aptible.com/activities?only_completed=true&read_only=true` |
| **Request Interval**    | `1m`                                                                         |
| **Request HTTP Method** | `GET`                                                                        |

<Note>
  See [Activity Details](/docs/core-concepts/observability/activity/activity-details) for the full list of event types. Certain types of events can be omitted by setting `read_only=false` in the URL.

  The `only_completed=true` parameter omits activity operations that are still in a `queued` or `running` state, so you only ingest events once they've reached a final state (`succeeded` or `failed`). If you set  `only_completed=false`, in-progress operations will be ingested immediately and the records will be later updated when it is complete.
</Note>

#### Request Transforms

Add the following request transforms, and *be sure to replace the placeholder with your actual token*:

```yaml theme={null}
- set:
    target: header.Authorization
    value: "Bearer APTIBLE_TOKEN_PLACEHOLDER"
- set:
    target: url.params.updated_after
    value: "[[.cursor.updated_after]]"
    default: "2025-11-01T00:00:00Z"
```

#### Response Split

Configure response splitting so each activity event becomes its own document:

```yaml theme={null}
target: body.activities
```

#### Response Pagination

Configure pagination to follow `next` links in the Activity API response:

```yaml theme={null}
- set:
    target: url.value
    value: '[[if (index .last_response.body._links "next")]][[.last_response.body._links.next.href]][[end]]'
    fail_on_template_error: true
```

#### Custom request cursor

Configure the cursor to track your position across polling intervals. `updated_after` is the integration's saved checkpoint — it determines where the next poll resumes. This ensures each request only fetches events updated since the last successful poll:

```yaml theme={null}
updated_after:
  value: "[[.last_event.updated_at]]"
```

#### Choose an agent policy

In the **Where to add this integration?** section, assign the integration to an agent policy. An agent policy manages a group of integrations deployed to a set of Elastic Agents. You can select an existing policy or click **Create a new agent policy** to create a new one.

This integration only needs to run on a single agent — it polls the Activity API on the configured interval and ingests all events centrally.

<Note>
  The Elastic Agent must have persistent storage so that cursor state survives restarts. If the agent loses its state (e.g. it runs on a container with an ephemeral filesystem), the cursor resets and the next poll starts from the beginning — re-fetching all historical events. The ingest pipeline's `_id` de-duplication prevents duplicate documents, but the agent will perform unnecessary work re-ingesting events it has already processed.
</Note>


# Logging Provider
Source: https://www.aptible.com/docs/core-concepts/observability/activity/integrations/logging-provider

Stream Aptible activity events to your logging provider using a self-hosted forwarding container

Stream [Activity](/docs/core-concepts/observability/activity/overview) events from Aptible to any Logstash-supported destination using Aptible's `activity-forwarder` container. The forwarder uses Filebeat (HTTPJSON input) and Logstash to poll the Activity API and forward events to a configurable output.

## Prerequisites

* A [long-term activity access token](/docs/core-concepts/security-compliance/access-permissions#activity-log-viewer) (coming soon!)
* A dedicated Aptible App to run the forwarder

## Supported Destinations

This guide includes configuration for **Sumo Logic**. For other providers, contact [Aptible Support](https://app.aptible.com/support) for guidance.

## Setup

### Step 1: Create an App

Create a new Account and App on Aptible to host the forwarder. This App will have access to a long-term token with full visibility into your organization's Activity, so only grant access to its Environment to roles and users for whom that level of access is appropriate.

<Warning>
  Do not add a Log Drain to this Account yet. The forwarder starts in a preview mode that prints the initial backfill window (the last 30 days of activity by default) to stdout, which could be tens or hundreds of thousands of lines.
</Warning>

### Step 2: Deploy the Forwarder

Deploy the forwarder image with your activity token:

```bash theme={null}
aptible deploy --app ${HANDLE} --docker-image aptible/activity-forwarder \
  "APTIBLE_ACTIVITY_ACCESS_TOKEN=long_term_token_placeholder"
```

### Step 3: Configure Service Settings

Set the service to use a simple health check and a longer stop timeout to handle releases and restarts gracefully:

```bash theme={null}
aptible services:settings --app ${HANDLE} cmd --simple-health-check --stop-timeout 60
```

### Step 4: Verify the Connection

Stream the app's logs and confirm that recent activities appear. Events should show up within about two minutes:

```bash theme={null}
aptible logs --app ${HANDLE}
```

```
Connected to logs from log-tail-zyvwad
User Login by Alex Kubacki at 2026-03-18T20:20:26.312Z
App Configure by Alex Kubacki at 2026-03-18T20:20:32.823Z
```

### Step 5: Request Persistent Storage

<Warning>
  Contact Aptible Support to attach a persistent volume to this container before proceeding. Without persistent storage, the forwarder's cursor resets on every restart, causing it to re-send the last 30 days of activity to your destination.
</Warning>

### Step 6: Configure Your Destination

Set `OUTPUT_CONFIG` to forward events to your provider. The value should be a complete Logstash `output { ... }` block.

#### Sumo Logic

Set up a new HTTP source in Sumo Logic and copy the pre-signed URL. The default settings will work. Then configure the output:

```bash theme={null}
aptible config:set --app ${HANDLE} OUTPUT_CONFIG='output {
    http {
      url => "https://endpoint4.collection.sumologic.com/receiver/v1/http/YOUR_TOKEN"
      http_method => "post"
      format => "json"
      content_type => "application/json"
    }
  }'
```

### Step 7: Confirm Events Are Arriving

Verify that activity events are appearing in your destination. The initial backfill covers 30 days by default, and new completed activity typically appears within about two minutes.

### Step 8: Enable Cursor Persistence

After persistent storage is attached (Step 5), disable cursor cleanup so the forwarder resumes from its saved position after restarts instead of re-importing the backfill window:

```bash theme={null}
aptible config:set --app ${HANDLE} CLEAN_CURSOR=false
```


# Navigating Activity in the UI
Source: https://www.aptible.com/docs/core-concepts/observability/activity/navigating-activity

Learn how to find and explore activity using the Aptible Dashboard

# Resource Activity Tabs

Apps, Databases, Endpoints, and LLM Keys each have a dedicated Activity tab on their detail pages. This makes it easy to review changes and operations for a single resource without sifting through organization-wide activity.

To view activity for a specific resource:

1. Navigate to the resource's detail page in the Dashboard
2. Click the **Activity** tab

The Activity tab displays the same information as the Activity Dashboard, but filtered to that specific resource.

# Activity Dashboard

The Activity dashboard provides a real-time and historic view of operations for active resources. Through the [Activity page](https://app.aptible.com/activity), you can:

* View activity for resources you have permission to access
* Search and filter activity using multiple criteria
* View operation logs for debugging purposes

<Note>
  Activity may have the Actor **Name (Aptible Staff)**. This indicates activity that was taken by an Aptible team member or platform automation as part of platform operations or support.
</Note>

## Timestamps

Timestamps are displayed in UTC by default. You can toggle between UTC and your browser's local timezone using the UTC/Local toggle in the top right of the Activity dashboard.

## Search and Filter Options

The Activity dashboard provides several search fields to help you find specific activity:

* **Date Range**: Select any custom date range, or choose from presets for the last 7, 30, or 90 days.
* **Operation Type**: Filter by Operation type (e.g., App Deploy, Database Provision, User logged in)
* **Status**: Filter by activity status (e.g., Queued, Running, Succeeded, Failed, Canceled)
* **Actor**: Filter by the user that initiated the activity
* **Environment**: Filter by specific environment

The search field can additionally narrow the results based on the contents of the "Target" and "Additional Info" columns.

Each activity event in the results includes a link on the right side of the row that opens a detailed view with additional information about that activity.

## Activity Detail View

Click any activity event to open its detail page. The detail view includes:

* **Additional Info**: A summary of the activity, when available.
* **Note**: Context about the activity, such as why an operation was initiated. Notes may include links to related resources or tickets.
* **Activity JSON**: The complete activity data in JSON format for detailed inspection.
* **Logs**: For operation-related activities, the operation logs.

<Tip>Troubleshooting with our team? You can share the URL of the Activity detail view (eg `https://app.aptible.com/activity/1234`) with the Aptible Support team for best success.</Tip>

## Exporting Activity Data

We support CSV and [newline-delimited JSON](https://jsonlines.org/) formats for exporting activity data. To export, simply apply any desired filters and click the "Export" button in the top right of the Activity dashboard.

The exported file will include all activity events matching the applied filters. The exported data includes the same fields as the Activity dashboard, along with additional metadata such as resource IDs and operation IDs. It matches the data you can see by opening an individual activity in the Activity dashboard.

The files are compressed with gzip, and are named `aptible_activity_export_[some other ids].csv.gz` or `aptible_activity_export_[some other ids].jsonl.gz`. Your operating system will likely be able to decompress these by double-clicking on them. The following command line run from your preferred Terminal application will also work:

```shell theme={null}
gunzip aptible_activity_export_[some other ids].csv.gz
```

We have seen some instances where macOS will quarantine and export file. You'll see an error saying:

> Apple could not verify "aptible\_activity\_export\_\[some other ids].jsonl" is free of malware that may harm your Mac or compromise your privacy.

We believe this happens, because the files have a `.jsonl.gz` or `.csv.gz` extension making them more likely to be flagged.

Remove the quarantine status with in your preferred Terminal with:

```shell theme={null}
xattr -d com.apple.quarantine aptible_activity_export_[some other ids].jsonl.gz
```


# Activity
Source: https://www.aptible.com/docs/core-concepts/observability/activity/overview

Learn about tracking changes to your resources with Activity

<img alt="" />

## Overview

Activity is a collective record of [operations](/docs/core-concepts/architecture/operations) and other audited events in your Aptible organization, including: user authentication attempts, role membership changes for users, permission updates to roles, and other configuration changes.

You can access and review Activity through the following methods:

1. **Activity Dashboard:** To view and search activity across your entire organization, you can explore the [Activity dashboard](/docs/core-concepts/observability/activity/navigating-activity#activity-dashboard)
2. **Resource Activity Tabs:** To focus on a particular resource, you can view activity within that resource's dedicated [Activity tab](/docs/core-concepts/observability/activity/navigating-activity#resource-activity-tabs).
3. **Activity Reports**: You can export [Activity Reports](/docs/core-concepts/observability/activity/activity-reports) for all past operations.
4. **SIEM/Logging Integration**: You can stream activity events to your SIEM or logging provider for centralized monitoring and alerting. Learn more about [SIEM/Logging Integration](/docs/core-concepts/observability/activity/integrations).

Users can only view activity for environments which they have permission to access.

For a complete list of all tracked activity event types, see [Activity Details](/docs/core-concepts/observability/activity/activity-details).


# Elasticsearch Log Drains
Source: https://www.aptible.com/docs/core-concepts/observability/logs/log-drains/elasticsearch-log-drains



# Overview

Aptible can deliver your logs to an [Elasticsearch](/docs/core-concepts/managed-databases/supported-databases/elasticsearch) database hosted in the same Aptible [Environment](/docs/core-concepts/architecture/environments).

# Ingest Pipelines

Elasticsearch Ingest Pipelines are supported on Aptible but not currently exposed in the UI. To set up an Ingest Pipeline, please contact [Aptible Support](/docs/how-to-guides/troubleshooting/aptible-support).

# Get Started

<Card title="Setting up a ELK stack on Aptible" icon="books" href="https://www.aptible.com/docs/elk-stack">
  Step-by-step instructions on setting up logging to an Elasticsearch database on Aptible
</Card>


# HTTPS Log Drains
Source: https://www.aptible.com/docs/core-concepts/observability/logs/log-drains/https-log-drains



# Overview

Aptible can deliver your logs via HTTPS.

The logs are delivered via HTTPS POST, using a JSON `Content-Type`.

# Payload

The payload is structured as follows. New keys may be added over time, and logs from [Ephemeral SSH Sessions](/docs/core-concepts/apps/connecting-to-apps/ssh-sessions) include additional keys.

```json theme={null}
{
  "@timestamp": "2017-01-11T11:11:11.111111111Z",
  "log": "some log line from your app",
  "stream": "stdout",
  "time": "2017-01-11T11:11:11.111111111Z",
  "@version": "1",
  "type": "json",
  "file": "/tmp/dockerlogs/containerId/containerId-json.log",
  "host": "containerId",
  "offset": "123",
  "layer": "app",
  "service": "app-web",
  "app": "app",
  "app_id": "456",
  "source": "app",
  "container": "containerId"
}
```

# Specific Metadata

Both [Ephemeral SSH Sessions](/docs/core-concepts/apps/connecting-to-apps/ssh-sessions) and [Endpoint Logs](/docs/core-concepts/apps/connecting-to-apps/app-endpoints/https-endpoints/endpoint-logs) contain additional metadata; see the appropriate documentation for further details.

# Get Started

<Card title="Setting up a HTTP Log Drain on Aptible" icon="books" href="https://www.aptible.com/docs/self-hosted-https-log-drain">
  Step-by-step instructions on setting up logging to an HTTP Log Drain on Aptible
</Card>


# Log Drains
Source: https://www.aptible.com/docs/core-concepts/observability/logs/log-drains/overview

Learn about sending Logs to logging destinations

<img alt="" />

Log Drains let you route Logs to logging destinations for reviewing, searching, and alerting. Log Drains support capturing logs for Apps, Databases, SSH sessions, and Endpoints.

# Explore Log Drains

<CardGroup>
  <Card title="Datadog" icon="book" href="https://www.aptible.com/docs/datadog" />

  <Card title="Custom - HTTPS" icon="book" href="https://www.aptible.com/docs/https-log-drains" />

  <Card title="Custom - Syslog" icon="book" href="https://www.aptible.com/docs/syslog-log-drains" />

  <Card title="Elasticsearch" icon="book" href="https://www.aptible.com/docs/elasticsearch-log-drains" />

  <Card title="Logentries" icon="book" href="https://www.aptible.com/docs/syslog-log-drains" />

  <Card title="Mezmo" icon="book" href="https://www.aptible.com/docs/mezmo" />

  <Card title="Papertrail" icon="book" href="https://www.aptible.com/docs/papertrail" />

  <Card title="Sumo Logic" icon="book" href="https://www.aptible.com/docs/sumo-logic" />
</CardGroup>


# Syslog Log Drains
Source: https://www.aptible.com/docs/core-concepts/observability/logs/log-drains/syslog-log-drains



# Overview

Aptible can deliver your logs via Syslog to a destination of your choice. This option makes it easy to use third-party providers such as [Logentries](https://logentries.com/) or [Papertrail](https://papertrailapp.com/) with Aptible.

> ❗️ When sending logs to a third-party provider, make sure your logs don't include sensitive or regulated information, or that you have the proper agreement in place with your provider.

# TCP-TLS-Only

Syslog [Log Drains](/docs/core-concepts/observability/logs/log-drains/overview) exclusively support TCP + TLS as the transport. This means you cannot deliver your logs over unencrypted and insecure channels, such as UDP or plaintext TCP.

# Logging Tokens

Syslog [Log Drains](/docs/core-concepts/observability/logs/log-drains/overview) lets you inject a prefix in all your log lines. This is useful with providers such as Logentries, which require a logging token to associate the logs you send with your account.

# Get Started

<Card title="Setting up a logging to Papertrail" icon="books" href="https://www.aptible.com/docs/papertrail">
  Step-by-step instructions on setting up logging to Papertrail
</Card>


# Logs
Source: https://www.aptible.com/docs/core-concepts/observability/logs/overview

Learn about how to access and retain logs from your Aptible resources

# Overview

With each operation, the output of your [Containers](/docs/core-concepts/architecture/containers/overview) is collected as Logs. This includes changes to your resources such as scaling, deploying, updating environment variables, creating backups, etc.

<Note> Strictly speaking, `stdout` and `stderr` are captured. If you are using Docker locally, this is what you'd see when you run `docker logs ...`. Most importantly, this means **logs sent to files are not captured by Aptible logging**, so when you deploy your [Apps](/docs/core-concepts/apps/overview) on Aptible, you should ensure you are logging to `stdout` or `stderr`, and not to log files.</Note>

# Quick Access Logs

Aptible streams live Logs for quick access. For long term retention of logs, you will need to set up a [Log Drain](/docs/core-concepts/observability/logs/log-drains/overview).

<Tabs>
  <Tab title="Using the CLI">
    App and Database logs can be accessed in real-time from the [CLI](/docs/reference/aptible-cli/overview) using the [`aptible logs`](/docs/reference/aptible-cli/cli-commands/cli-logs) command. Upon executing this command, only the logs generated from that moment onward will be displayed.

    Example:

    ```
    aptible logs --app "$APP_HANDLE"
    aptible logs --database "$DATABASE_HANDLE"
    ```
  </Tab>

  <Tab title="Using the the Aptible Dashboard">
    <img alt="" />

    Within the Aptible Dashboard, logs for recent operations can be acccessed by viewing recent [Activity](/docs/core-concepts/observability/activity/overview).
  </Tab>
</Tabs>

# Log Integrations

## Log Drains

Log Drains let you route Logs to logging destinations for reviewing, searching, and alerting. Log Drains support capturing logs for Apps, Databases, SSH sessions, and Endpoints.

<Card title="Learn more about Log Drains" icon="book" href="https://www.aptible.com/docs/log-drains" />

## Log Archiving

Log Archiving lets you route Logs to S3 for business continuity and compliance. Log Archiving supports capturing logs for Apps, Databases, SSH sessions, and Endpoints.

<Card title="Learn more about Log Archiving" icon="book" href="https://www.aptible.com/docs/s3-log-archives" />


# Log Archiving to S3
Source: https://www.aptible.com/docs/core-concepts/observability/logs/s3-log-archives



<Info> S3 Log Archiving is currently in limited beta release and is only available on the [Enterprise plan](https://www.aptible.com/pricing). Please note that this feature is subject to limited availability while in the beta release stage. </Info>

Once you have configured [Log Drains](/docs/core-concepts/observability/logs/log-drains/overview) for daily access to your logs (e.g., for searching and alerting purposes), you should also configure backup log delivery to Amazon S3. Having this backup method will help ensure that, in the event, your primary logging provider experiences delivery or availability issues, your ability to retain logs for compliance purposes will not be impacted.

Aptible provides this disaster-recovery option by uploading archives of your container logs to an S3 bucket owned by you, where you can define any retention policies as needed.

# Setup

## Prerequisites

To begin sending log archives to an S3 bucket, you must have your own AWS account and an S3 bucket configured for this purpose.

This must be the sole purpose of your S3 bucket (that is, do not add other content to this bucket), your S3 bucket **must** have versioning enabled, and your S3 bucket **must** be in the same region as your Stack. To enable [S3 bucket versioning](https://docs.aws.amazon.com/AmazonS3/latest/userguide/Versioning.html) via the AWS Console, visit the Properties tab of your S3 bucket, click Edit under Bucket Versioning, choose Enable, and then Save Changes.

## Process

Once you have created a bucket and enabled versioning, apply the following policy to the bucket in order to allow Aptible to replicate objects to it.

<Warning> You need to replace `YOUR_BUCKET_NAME` in both "Resource" sections with the name of your bucket. </Warning>

```json theme={null}
{
  "Version": "2012-10-17",
  "Id": "Aptible log sync",
  "Statement": [
    {
      "Sid": "dest_objects",
      "Effect": "Allow",
      "Principal": {
        "AWS": "arn:aws:iam::916150859591:role/s3-stack-log-replication"
      },
      "Action": [
        "s3:ReplicateObject",
        "s3:ReplicateDelete",
        "s3:ObjectOwnerOverrideToBucketOwner"
      ],
      "Resource": "arn:aws:s3:::YOUR_BUCKET_NAME/*"
    },
    {
      "Sid": "dest_bucket",
      "Effect": "Allow",
      "Principal": {
        "AWS": "arn:aws:iam::916150859591:role/s3-stack-log-replication"
      },
      "Action": [
        "s3:List*",
        "s3:GetBucketVersioning",
        "s3:PutBucketVersioning"
      ],
      "Resource": "arn:aws:s3:::YOUR_BUCKET_NAME"
    }
  ]
}
```

Contact [Aptible Support](/docs/how-to-guides/troubleshooting/aptible-support) to request access to this limited beta. We will need to know:

* Your AWS Account ID.
* The name of your S3 bucket to use for archiving.

# Delivery

To ensure you only need to read or process each file once, we do not upload any files which are actively being written to. This means we will only upload a log archive file when either of two conditions is met:

* After the container has exited, the log file will be eligible for upload.
* If the container log exceeds 500 MB, we will rotate the log, and the rotated file will be eligible for upload.

Aptible will upload log files at the bottom of every hour (1:30, 2:30, etc.).

If you have long-running containers that generate a low volume of logs, you may need to restart the App or Database periodically to flush the log archives to S3. As such, this feature is only intended to be used as a disaster archive for compliance purposes, not for the troubleshooting of running services, data processing pipelines, or any usage that mandates near-realtime access.

# Retrieval

You should not need access the log files from your S3 bucket directly, as Aptible has provided a command in our [CLI](/docs/reference/aptible-cli/cli-commands/overview) that provides you the ability to search, download and decrypt your container logs: [`aptible logs_from_archive`](/docs/reference/aptible-cli/cli-commands/cli-logs-from-archive).

This utility has no reliance on Aptible's services, and since the S3 bucket is under your ownership, you may use it to access your Log Archive even if you are no longer a customer of Aptible.

# File Format

## Encryption

Files stored in your S3 bucket are encrypted with an AES-GCM 256-bit key, protecting your data in transit and at rest in your S3 bucket. Decryption is handled automatically upon retrieval via the Aptible CLI.

## Compression

The files are stored and downloaded in gzip format to minimize storage and transfer costs.

## JSON Format

Once uncompressed, the logs will be in the [JSON format as emitted by Docker](https://docs.docker.com/config/containers/logging/json-file/). For example:

```json theme={null}
{"log":"Log line is here\n","stream":"stdout","time":"2022-01-01T12:23:45.5678Z"}
{"log":"An error may be here\n","stream":"stderr","time":"2022-01-01T12:23:45.5678Z"}
```


# InfluxDB Metric Drain
Source: https://www.aptible.com/docs/core-concepts/observability/metrics/metrics-drains/influxdb-metric-drain

Learn about sending Aptible logs to an InfluxDB

Aptible can deliver your [Metrics](/docs/core-concepts/observability/metrics/overview) to any InfluxDB Database (hosted on Aptible or not). There are two types of InfluxDB Metric Drains on Aptible:

* Aptible-hosted: This method allows you to route metrics to an InfluxDB Database hosted on Aptible. This Database must live in the same Environment as the Metrics you are retrieving. Additionally, the [Aptible Metrics Terraform Module](https://registry.terraform.io/modules/aptible/metrics/aptible/latest) uses this method to deploy prebuilt Grafana dashboards with alerts for monitoring RAM & CPU usage for your Apps & Databases - so you can instantly start monitoring your Aptible resources.
* Hosted anywhere: This method allows you to route Metrics to any InfluxDB. This might be useful if you are leveraging InfluxData's [hosted InfluxDB offering](https://www.influxdata.com/).

# InfluxDB Metrics Structure

Aptible InfluxDB Metric Drains publish metrics in a series named `metrics`.

The following values are published (approximately every 30 seconds):

* `running`: a boolean indicating whether the Container was running when this point was sampled.
* `milli_cpu_usage`: the Container's average CPU usage (in milli CPUs) over the reporting period.
* `milli_cpu_limit`: the maximum CPU accessible to the container.
* `memory_total_mb`: the Container's total memory usage.
* `memory_rss_mb`: the Container's RSS memory usage. This memory is typically not reclaimable. If this exceeds the `memory_limit_mb`, the container will be restarted.
* `memory_limit_mb`: the Container's [Memory Limit](/docs/core-concepts/scaling/memory-limits).
* `disk_read_kbps`: the Container's average disk read bandwidth over the reporting period.
* `disk_write_kbps`: the Container's average disk write bandwidth over the reporting period.
* `disk_read_iops`: the Container's average disk read IOPS over the reporting period.
* `disk_write_iops`: the Container's average disk write IOPS over the reporting period.
* `disk_usage_mb`: the Database's Disk usage (Database metrics only).
* `disk_limit_mb`: the Database's Disk size (Database metrics only).
* `pids_current`: the current number of tasks in the Container (see [Other Limits](/docs/core-concepts/security-compliance/ddos-pid-limits)).
* `pids_limit`: the maximum number of tasks for the Container (see [Other Limits](/docs/core-concepts/security-compliance/ddos-pid-limits)).

> 📘 Review [Understanding Memory Utilization](/docs/core-concepts/scaling/memory-limits#understanding-memory-utilization) for more information on the meaning of the `memory_total_mb` and `memory_rss_mb` values.

> 📘 Review [I/O Performance](/docs/core-concepts/scaling/database-scaling#i-o-performance) for more information on the meaning of the `disk_read_iops` and `disk_write_iops` values.

All points are enriched with the following tags:

* `environment`: Environment handle
* `app`: App handle (App metrics only)
* `database`: Database handle (Database metrics only)
* `service`: Service name
* `host_name`: [Container Hostname (Short Container ID)](/docs/core-concepts/architecture/containers/overview#container-hostname)
* `container`: full Container ID

# Getting Started

<AccordionGroup>
  <Accordion title="Creating a Influx Metric Drain">
    You can set up an InfluxDB Metric Drain in the following ways:

    * (Aptible-hosted only) Using [Aptible Metrics Terraform Module](https://registry.terraform.io/modules/aptible/metrics/aptible/latest). This provision an Influx Metric Drain with pre-built Grafana dashboards and alerts for monitoring RAM & CPU usage for your Apps & Databases. This simplifies the setup of Metric Drains so you can start monitoring your Aptible resources immediately, all hosted within your Aptible account.
    * Within the Aptible Dashboard by navigating to the respective Environment > selecting the "Metrics Drain" tab > selecting "Create Metric Drain" > selecting "InfluxDB (This Environment)" or "InfluxDB (Anywhere)"
      <img alt="" />
    * Using the [`aptible metric_drain:create:influxdb`](/docs/reference/aptible-cli/cli-commands/cli-metric-drain-create-influxdb) command
  </Accordion>

  <Accordion title="Accessing Metrics in DB">
    The best approach to accessing metrics from InfluxDB is to deploy [Grafana](https://grafana.com). Grafana is easy to deploy on Aptible.

    * **Recommended:** [Using Aptible Metrics Terraform Module](https://registry.terraform.io/modules/aptible/metrics/aptible/latest). This provisions Metric Drains with pre-built Grafana dashboards and alerts for monitoring RAM & CPU usage for your Apps & Databases. This simplifies the setup of Metric Drains so you can start monitoring your Aptible resources immediately, all hosted within your Aptible account.
    * You can also follow this tutorial [Deploying Grafana on Aptible](https://www.aptible.com/docs/deploying-grafana-on-deploy), which includes suggested queries to set up within Grafana.
  </Accordion>
</AccordionGroup>


# Metrics Drains
Source: https://www.aptible.com/docs/core-concepts/observability/metrics/metrics-drains/overview

Learn how to route metrics with Metric Drains

![](https://assets.tina.io/0cc6fba2-0b87-4a6a-9953-a83971f2e3fa/App_UI_Create_Metric_Drain.png)

# Overview

Metric Drains lets you route metrics for [Apps](/docs/core-concepts/apps/overview) and [Databases](/docs/core-concepts/managed-databases/managing-databases/overview) to the destination of your choice. Metrics Drains are typically useful to:

* Persist metrics for the long term

* Alert when metrics cross thresholds of your choice

* Troubleshoot performance problems

# Explore Metric Drains

<CardGroup>
  <Card title="Datadog" icon="book" href="https://www.aptible.com/docs/datadog" />

  <Card title="InfluxDB" icon="book" href="https://www.aptible.com/docs/influxdb-metric-drain" />
</CardGroup>


# Metrics
Source: https://www.aptible.com/docs/core-concepts/observability/metrics/overview

Learn about container metrics on Aptible

## Overview

<img alt="" />

Aptible provides key metrics for your app and database containers, such as memory, CPU, and disk usage, and provides them in two forms:

* **In-app metrics:** Metric visualizations within the Aptible Dashboard, enabling real-time monitoring

* **Metric Drains:** Send to a destination of your choice for monitoring, alerting, and long-term retention

Aptible provides in-app metrics conveniently within the Aptible Dashboard. This feature offers real-time monitoring with visualizations for quick insights.

The following metrics are available within the Aptible Dashboard

* Apps/Services:

  * Memory Usage

  * CPU Usage

  * Load Average

* Databases:

  * Memory Usage

  * CPU Usage

  * Load Average

  * Disk IO

  * Disk Usage

### Accessing in-app metrics

To access metrics in the Aptible Dashboard, select your app or database and click the **Metrics** tab.

<Info>
  Metrics are only available for apps and databases with at least one container running. If a service is scaled to zero containers, metrics will not be displayed.
</Info>

### Interpreting CPU Metrics

The Aptible Dashboard shows raw CPU usage. This value can exceed `100%` because it represents actual CPU consumption, not a normalized percentage of the Container's CPU limit.

Metric drains can report the same underlying CPU data differently depending on the destination. For example, in Datadog you may want to normalize CPU usage against the Container limit when building dashboards or alerts:

```text theme={null}
cpu% = enclave.milli_cpu_usage / enclave.milli_cpu_limit * 100
```

Normalized CPU values are useful for alerting because they remain comparable when you scale services. Raw CPU values are useful when you need to understand actual CPU consumption.

## Metric Drains

Metric Drains provide a powerful option for routing your metrics data to a destination of your choice for comprehensive monitoring, alerting, and long-term data retention.

<CardGroup>
  <Card title="Datadog" icon="book" href="https://www.aptible.com/docs/datadog" />

  <Card title="InfluxDB" icon="book" href="https://www.aptible.com/docs/influxdb-metric-drain" />

  <Card title="Collect Prometheus Metrics" icon="book" href="/how-to-guides/observability-guides/collect-prometheus-metrics-from-apps" />
</CardGroup>


# Observability
Source: https://www.aptible.com/docs/core-concepts/observability/overview

Learn about observability features on Aptible to help you monitor, analyze and manange your Apps and Databases

## Overview

Aptible’s observability tools are designed to provide a holistic view of your resources, enabling you to effectively monitor, analyze, and manage your Apps and Databases. This includes monitoring activity tracking for changes made to your resources, logs for real-time data or historical retention, and metrics for monitoring usage and performance.

## Activity

Aptible keeps track of all changes made to your resources as operations and records this as activity.

<Card title="Learn more about Activity" icon="book" href="https://www.aptible.com/docs/activity" />

## Logs

Aptible's log features ensure you have access to critical information generated by your containers. Logs come in three forms: CLI Logs (for quick access), Log Drains (for search and alerting), and Log Archiving (for business continuity and compliance).

<Card title="Learn more about Logs" icon="book" href="https://www.aptible.com/docs/logging" />

## Metrics

For real-time performance monitoring of your app and database containers, Aptible provides essential metrics, including memory usage, CPU usage, and disk utilization. These metrics are available as in-app visualizations or sent to a destination for monitoring and alerting.

<Card title="Learn more about Metrics" icon="book" href="https://www.aptible.com/docs/metrics" />


# Sources
Source: https://www.aptible.com/docs/core-concepts/observability/sources



# Overview

Sources allow you to relate your deployed Apps back to their source repositories, allowing you to use the Aptible Dashboard to answer the question "*what's deployed where?*"

# Configuring Sources

To connect your App with it's Source, you'll need to configure your deployment pipeline to send Source information along with your deployments. See [Linking Apps to Sources](/docs/core-concepts/apps/deploying-apps/linking-apps-to-sources) for more details.

# The Sources List

The Sources list view displays a list of all of the Sources configured across your deployed Apps. This view is useful for finding groups of Apps that are running code from the same Source (e.g., ephemeral environments or multiple instances of a single-tenant application).

<img alt="" />

# Source Details

From the Source list page, you can click into a Source to see its details, including a list of Apps deployed from the Source and their current revision information

<img alt="" />

You can also view the Deployments tab, which will display historical deployments and their revision information made from that Source across all of your Apps.

<img alt="" />


# App Scaling
Source: https://www.aptible.com/docs/core-concepts/scaling/app-scaling

Learn about scaling Apps CPU, RAM, and containers - manually or automatically

## Overview

Aptible Apps are scaled at the [Service](/docs/core-concepts/apps/deploying-apps/services) level, meaning each App Service is scaled independently.

App Services can be scaled by adding more CPU/RAM (vertical scaling) or by adding more containers (horizontal). App Services can be scaled manually via the CLI or UI, automatically with the Autoscaling, or programmatically with Terraform.

Apps with more than two containers are deployed in a high-availability configuration, ensuring redundancy across different zones.

When Apps are scaled, a new set of [containers](/docs/core-concepts/architecture/containers/overview) will be launched to replace the existing ones for each of your App's [Services](/docs/core-concepts/apps/deploying-apps/services).

## High-availability Apps

Apps scaled to 2 or more Containers are automatically deployed in a high-availability configuration, with Containers deployed in separate [AWS Availability Zones](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/using-regions-availability-zones.html).

## Horizontal Scaling

Scale Apps horizontally by adding more [Containers](/docs/core-concepts/architecture/containers/overview) to a given Service. Each App Service can scale up to 32 Containers via the Aptible Dashboard. Scaling above 32 containers for a service (with a maximum of 128 containers) is supported via the [Aptible CLI](https://www.aptible.com/docs/reference/aptible-cli/cli-commands/cli-apps-scale#aptible-apps-scale) and the [Aptible Terraform Provider.](https://registry.terraform.io/providers/aptible/aptible/latest)

<Note>Services with an attached [Persistent Disk](/docs/core-concepts/apps/persistent-disks) cannot be scaled horizontally. They must run on exactly one Container.</Note>

### Manual Horizontial Scaling

App Services can be manually scaled via the Dashboard or [`aptible apps:scale`](https://www.aptible.com/docs/reference/aptible-cli/cli-commands/cli-apps-scale) CLI command. Example:

```text theme={null}
  aptible apps:scale SERVICE [--container-count COUNT] 
```

### Horizontal Autoscaling

<Frame>
  <img alt="Horizontal Autoscaling" />
</Frame>

<Info>
  Horizontal Autoscaling is only available on the [Production and Enterprise plans.](https://www.aptible.com/pricing)
</Info>

When Horizontal Autoscaling is enabled on a Service, the autoscaler evaluates Services every 5 minutes and generates scaling adjusted based on CPU usage (as percentage of total cores). Data is analyzed over a 30-minute period. Autoscaling will not create a scaling operation when your service or app is already being scaled, configured, or deployed.  Post-scaling cooldowns are 5 minutes for scaling down and 1 minute for scaling up. After any release, an additional 5-minute cooldown applies. Metrics are evaluated at the 99th percentile aggregated across all of the service containers over the past 30 minutes.

This feature can also be configured via [Terraform](/docs/reference/terraform) or the [`aptible services:autoscaling_policy:set`](/docs/reference/aptible-cli/cli-commands/cli-services-autoscalingpolicy-set) CLI command.

By default, a [Horizontal Autoscaling Operation](https://www.aptible.com/docs/core-concepts/scaling/app-scaling#horizontal-autoscaling) follows the regular [Container Lifecycle](https://www.aptible.com/docs/core-concepts/architecture/containers/overview#container-lifecycle) and [Releases](https://www.aptible.com/docs/core-concepts/apps/deploying-apps/releases/overview#releases) pattern of restarting all current containers when modifying the number of running containers. However, this behavior can be disabled by enabling the **Restart Free Scaling** (`use_horizontal_scale` in Terraform) setting when configuring autoscaling for the service. With restart free scaling enabled, containers are added and removed without restarting the existing ones. When removing containers in this configuration, the service's stop timeout is still respected. Note that if the service has a [TCP](/docs/core-concepts/apps/connecting-to-apps/app-endpoints/tcp-endpoints), [TLS](/docs/core-concepts/apps/connecting-to-apps/app-endpoints/tls-endpoints), or [GRPC](/docs/core-concepts/apps/connecting-to-apps/app-endpoints/grpc-endpoints) endpoint, the regular full restart will still occur even with restart free scaling enabled. Additionally, if any endpoint associated with the service failed its most recent `provision` operation (which is an operation that is called on create of a new endpoint, or update of an existing endpoint), the regular full restart will still occur even with restart free scaling enabled.

<Card title="Guide for Configuring Horizontial Autoscaling" icon="book-open-reader" href="https://www.aptible.com/docs/how-to-guides/app-guides/horizontal-autoscaling-guide" />

#### Configuration Options

<AccordionGroup>
  <Accordion title="Container & CPU Threshold Settings" icon="gear">
    The following container & CPU threshold settings are available for configuration:

    <Info>
      CPU thresholds are expressed as a number between 0 and 1, reflecting the actual percentage usage of your container's CPU limit. For instance, 2% usage with a 12.5% limit equals 16%, or 0.16.
    </Info>

    * **Percentile**: Determines the percentile for evaluating RAM and CPU usage.
    * **Minimum Container Count**: Sets the lowest container count to which the service can be scaled down by Autoscaler.
    * **Maximum Container Count**: Sets the highest container count to which the service can be scaled up to by Autoscaler.
    * **Scale Up Steps**: Sets the amount of containers to add when autoscaling (ex: a value of 2 will go from 1->3->5). Container count will never exceed the configured maximum.
    * **Scale Down Steps**: Sets the amount of containers to remove when autoscaling (ex: a value of 2 will go from 4->2->1). Container count will never exceed the configured minimum.
    * **Scale Down Threshold (CPU Usage)**: Specifies the percentage of the current CPU usage at which an up-scaling action is triggered.
    * **Scale Up Threshold (CPU Usage)**: Specifies the percentage of the current CPU usage at which a down-scaling action is triggered.
  </Accordion>

  <Accordion title="Time-Based Settings" icon="gear">
    The following time-based settings are available for configuration:

    * **Metrics Lookback Time Interval**: The duration in seconds for retrieving past performance metrics.
    * **Post Scale Up Cooldown**: The waiting period in seconds after an automated scale-up before another scaling action can be considered. The period of time the service is on cooldown is still considered in the metrics for the next potential scale.
    * **Post Scale Down Cooldown**: The waiting period in seconds after an automated scale-down before another scaling action can be considered. The period of time the service is on cooldown is still considered in the metrics for the next potential scale.
    * **Post Release Cooldown**: The time in seconds to ignore following any general scaling operation, allowing stabilization before considering additional scaling changes. For this metric, the cooldown period is *not* considered in the metrics for the next potential scale.
  </Accordion>

  <Accordion title="General Settings" icon="gear">
    The following general settings are available for configuration:

    * **Restart Free Scaling**: When enabled, scale operations for modifying the number of running containers will not restart the other containers in the service.
  </Accordion>
</AccordionGroup>

## Vertical Scaling

Scale Apps vertically by changing the size of Containers, i.e., changing their [Memory Limits](/docs/core-concepts/scaling/memory-limits) and [CPU Limits](/docs/core-concepts/scaling/container-profiles). The available sizes are determined by the [Container Profile.](/docs/core-concepts/scaling/container-profiles)

### Manual Vertical Scaling

App Services can be manually scaled via the Dashboard or [`aptible apps:scale`](https://www.aptible.com/docs/reference/aptible-cli/cli-commands/cli-apps-scale) CLI command. Example:

```text theme={null}
    aptible apps:scale SERVICE [--container-size SIZE_MB]
```

### Vertical Autoscaling

<Frame>
  <img alt="Vertical Autoscaling" />
</Frame>

<Info>
  Vertical Autoscaling is only available on the [Enterprise plan.](https://www.aptible.com/pricing)
</Info>

When Vertical Autoscaling is enabled on a Service, the autoscaler also evaluates services every 5 minutes and generates scaling recommendations based:

* RSS usage in GB divided by the CPU
* RSS usage levels

Data is analyzed over a 30-minute lookback period. Autoscaling will not create a scaling operation when your service or app is already being scaled, configured, or deployed. Post-scaling cooldowns are 5 minutes for scaling down and 1 minute for scaling up. An additional 5-minute cooldown applies after a service release. Metrics are evaluated at the 99th percentile aggregated across all of the service containers over the past 30 minutes.

This feature can also be configured via [Terraform](/docs/reference/terraform) or the [`aptible services:autoscaling_policy:set`](/docs/reference/aptible-cli/cli-commands/cli-services-autoscalingpolicy-set) CLI command.

#### Configuration Options

<AccordionGroup>
  <Accordion title="RAM & CPU Threshold Settings" icon="gear">
    The following RAM & CPU Threshold settings are available for configuration:

    * **Percentile**: Sets the percentile of current RAM and CPU usage to use when evaluating autoscaling actions.
    * **Minimum Memory (MB)**: Sets the lowest container size the service can be scaled down to.
    * **Maximum Memory (MB)**: Sets the highest container size the service can be scaled up to. If blank, the container can scale to the largest size available.
    * **Memory Scale Up Percentage**: Specifies a threshold based on a percentage of the current memory limit at which the service's memory usage triggers a scale up.
    * **Memory Scale Down Percentage**: Specifies a threshold based on the percentage of the next smallest container size's memory limit at which the service's memory usage triggers a scale down.
    * **Memory Optimized Memory/CPU Ratio Threshold**: Establishes the ratio of Memory (in GB) to CPU (in CPUs) at which values exceeding the threshold prompt a shift to an R (Memory Optimized) profile.
    * **Compute Optimized Memory/CPU Ratio Threshold**: Sets the Memory-to-CPU ratio threshold, below which the service is transitioned to a C (Compute Optimized) profile.
  </Accordion>

  <Accordion title="Time-Based Settings" icon="gear">
    The following time-based settings are available for configuration:

    * **Metrics Lookback Time Interval**: The duration in seconds for retrieving past performance metrics.
    * **Post Scale Up Cooldown**: The waiting period in seconds after an automated scale-up before another scaling action can be considered. The period of time the service is on cooldown is still considered in the metrics for the next potential scale.
    * **Post Scale Down Cooldown**: The waiting period in seconds after an automated scale-down before another scaling action can be considered. The period of time the service is on cooldown is still considered in the metrics for the next potential scale.
    * **Post Release Cooldown**: The time in seconds to ignore following any general scaling operation, allowing stabilization before considering additional scaling changes. For this metric, the cooldown period is *not* considered in the metrics for the next potential scale.
  </Accordion>
</AccordionGroup>

***

## FAQ

<AccordionGroup>
  <Accordion title="How do I scale my apps and services?">
    See our guide here for [How to scale apps and services](https://www.aptible.com/docs/how-to-guides/app-guides/how-to-scale-apps-services)
  </Accordion>
</AccordionGroup>


# Container Efficiency Recommendations
Source: https://www.aptible.com/docs/core-concepts/scaling/container-efficiency-recommendations

Learn about using the in-app Container Efficiency Recommendations to optimize resource allocation and reduce costs

<Frame>
  ![Container Efficiency column showing status indicators](https://promptless-customer-doc-assets.s3.amazonaws.com/docs-images/org_37aJORR8byth21cNqyhLINvLKa8/container-efficiency-column-b5233df3.png)
</Frame>

## Overview

Container Efficiency recommendations appear in the Aptible Dashboard for App Services and Databases. You'll find the **Container Efficiency** column in the App Services and Database list views, with detailed recommendations on each resource's Scale page under **Insights and Recommendations**.

Each resource displays one of the following statuses:

* **Rightsized** - Your container is optimally sized for performance and cost efficiency
* **Under-provisioned** - Increase resources to meet demand and improve reliability
* **Over-provisioned** - Reduce resources to avoid overspending (shows potential savings)
* **Autoscaling** - Vertical scaling is being handled automatically (click to open autoscaling settings)

Recommendations are updated daily based on the last 14 days of data and provide vertical scaling suggestions for optimal container size and profile.

### Using Container Efficiency Recommendations

On the Scale page for any App Service or Database, the **Insights and Recommendations** section shows:

* Your current Container Efficiency status
* Potential monthly savings (for over-provisioned containers)
* A collapsible recommendation panel with detailed guidance

Click **See recommendation** to expand details, including:

* The recommended container size and profile
* CPU usage (95th percentile) and peak memory consumption from the last 14 days
* An **Autofill Changes** button to apply the recommendation to the scaling form
* A **View Metrics** button to review your service's metrics

Hover over the status pill for a quick summary of your resource's CPU and memory usage over the last 14 days.

## How does Aptible make manual vertical scale right-sizing recommendations?

Here are the key details of how the recommendations are generated:

* Aptible looks at the App and Database metrics within the last **14 days**

* There are two primary metrics:

  * CPU usage: **95th percentile** within the time window

  * RAM usage: **max RSS value** within the time window

* For specific databases, Aptible will modify the current RAM usage:

  * When PostgreSQL, MySQL, MongoDB: make a recommendation based on **30% of max RSS value** within the time window

  * When Elasticsearch, Influxdb: make a recommendation based on **50% of max RSS
    value** within the time window

* Then, Aptible finds the most optimial [Container Profile](https://www.aptible.com/docs/core-concepts/scaling/container-profiles) and size that fits within the
  CPU and RAM usage:

  * If the recommended cost savings is less than \$150/mo, Aptible won't offer the
    recommendation

  * If the recommended container size change is a single step down (e.g.
    downgrade from 4GB to 2GB), Aptible won't offer the recommendation

## Why does Aptible increase the RAM usage for certain databases?

For some databases, the maintainers recommend having greater capacity than what
is currently being used.  Therefore, Aptible has unique logic that allows those databases to
adhere to their recommendations. We have a section specifically about [Understanding Memory Utilization](https://www.aptible.com/docs/core-concepts/scaling/memory-limits#understanding-memory-utilization) where you can learn more.

Because Aptible does not have knowledge of how these databases are being used, we have
to make best guesses and use the most common use cases to set sane defaults for the
databases we offer as well as our right-sizing recommendations.

### PostgreSQL

We set the manual recommendations to scale based on **30% of the max RSS
value** within the time window. This means if a PostgreSQL database uses more than 30% of the available memory, Aptible will recommend a scale-up and, conversely, scaling down.

We make this recommendation based on setting the `shared_buffers` to 25% of the
total RAM, which is the [recommended starting value](https://www.postgresql.org/docs/current/runtime-config-resource.html#GUC-SHARED-BUFFERS):

> If you have a dedicated database server with 1GB or more of RAM, a reasonable starting value for shared\_buffers is 25% of the memory in your system.

Other References:

* [https://www.geeksforgeeks.org/postgresql-memory-management/](https://www.geeksforgeeks.org/postgresql-memory-management/)

* [https://www.enterprisedb.com/postgres-tutorials/how-tune-postgresql-memory](https://www.enterprisedb.com/postgres-tutorials/how-tune-postgresql-memory)

### MySQL

We set the manual recommendations to scale based on **30% of the max RSS
value** within the time window.

We make this recommendation based on setting the `innodb_buffer_pool_size` to
50% of the total RAM.

From the MySQL[ docs](https://dev.mysql.com/doc/refman/8.4/en/innodb-parameters.html#sysvar_innodb_buffer_pool_size):

> A larger buffer pool requires less disk I/O to access the same table data more than once. On a dedicated database server, you might set the buffer pool size to 80% of the machine's physical memory size.

### MongoDB

We set the manual recommendations to scale based on **30% of the max RSS
value** within the time window.

We make this recommendation based on the [default WiredTiger internal cache set
to 50% of total RAM - 1GB](https://www.mongodb.com/docs/manual/administration/production-notes/#allocate-sufficient-ram-and-cpu):

> With WiredTiger, MongoDB utilizes both the WiredTiger internal cache and the filesystem cache. The default WiredTiger internal cache size is the larger of either: 50% of (RAM - 1 GB), or 256 MB.

### ElasticSearch

We set the manual recommendations to scale based on **50% of the max RSS
value** within the time window.

We make this recommendation based on [setting the heap size 50% of total RAM](https://www.elastic.co/guide/en/elasticsearch/guide/master/heap-sizing.html#_give_less_than_half_your_memory_to_lucene):

> The standard recommendation is to give 50% of the available memory to Elasticsearch heap, while leaving the other 50% free. It won’t go unused; Lucene will happily gobble up whatever is left over.

Other References:

* [https://www.elastic.co/guide/en/elasticsearch/reference/current/advanced-configuration.html#set-jvm-heap-size](https://www.elastic.co/guide/en/elasticsearch/reference/current/advanced-configuration.html#set-jvm-heap-size)

### InfluxDB

We set the manual recommendations to scale based on **50% of the max RSS
value** within the time window.

We make this recommendation based on [InfluxDB's memory management](https://docs.influxdata.com/influxdb/v1/guides/hardware_sizing/#memory), which recommends having sufficient memory headroom for query processing, caching, and write operations. InfluxDB benefits from additional memory for its in-memory indexes and query caching layers.


# Container Profiles
Source: https://www.aptible.com/docs/core-concepts/scaling/container-profiles

Learn about using Container Profiles to optimize spend and performance

## Overview

<Info>
  CPU-Optimized (C) and Memory Optimized (R) Container Profiles are only available on [Production and Enterprise plans.](https://www.aptible.com/pricing)
</Info>

Container Profiles provide flexibility and cost-optimization by allowing users to select the workload-appropriate Profile. Aptible offers three Container Profiles with unique CPU-to-RAM ratios and sizes:

* **General Purpose (M):** The default Container Profile, which works well for most use cases.
* **CPU-Optimized (C):** For CPU-constrained workloads, this Profile provides high-performance CPUs and more CPU per GB of RAM.
* **Memory Optimized (R):** For memory-constrained workloads, this Profile provides more RAM for each CPU allocated to the Container.

The General Purpose (M) Container Profile is available by default on all [Stacks](/docs/core-concepts/architecture/stacks). CPU-Optimized (C) and Memory Optimized (R) Container Profiles are only available on [Dedicated Stacks.](/docs/core-concepts/architecture/stacks#dedicated-stacks)

All new Apps & Databases are created with the General Purpose (M) Container Profile by default. This applies to [Database Backups](/docs/core-concepts/managed-databases/managing-databases/database-backups) and [Database Replicas.](/docs/core-concepts/managed-databases/managing-databases/replication-clustering)

## Specifications per Container Profile

| Container Profile    | Default | Available Stacks   | CPU:RAM Ratio   | RAM per CPU | Container Sizes | Cost           |
| -------------------- | ------- | ------------------ | --------------- | ----------- | --------------- | -------------- |
| General Purpose (M)  | ✔️      | Shared & Dedicated | 1/4 CPU:1GB RAM | 4GB/CPU     | 512MB-240GB     | \$0.08/GB/Hour |
| Memory Optimized (R) |         | Dedicated          | 1/8 CPU:1GB RAM | 8GB/CPU     | 4GB-752GB       | \$0.05/GB/Hour |
| CPU-Optimized (C)    |         | Dedicated          | 1/2 CPU:1GB RAM | 2GB/CPU     | 2GB-368GB       | \$0.10/GB/Hour |

## Supported Availability Zones

It is important to note that not all container profiles are available in every AZ, whether for app or database containers. In the event that this occurs during a scaling operation:

* **App Containers:** Aptible will handle the migration of app containers to an AZ that supports the desired container profile seamlessly and with zero downtime, requiring no additional action from the user.
* **Database Containers:** However, for database containers, Aptible will prevent the scaling operation and log an error message, indicating that it is necessary to move the database to a new AZ that supports the desired container profile. This process requires a full disk backup and restore but can be easily accomplished using Aptible's 1-click "Database Restart + Backup + Restore.” It is important to note that this operation will result in longer downtime and completion time than typical scaling operations. For more information on resolving this error, including expected downtime, please refer to our troubleshooting guide.

***

## FAQ

<Accordion title="How do I modify the Container Profile for an App or Database?">
  Container Profiles can only be modified from the Aptible Dashboard when scaling the app/service or database.  The Container Profile will take effect upon restart.

  <img alt="" />
</Accordion>


# CPU Allocation
Source: https://www.aptible.com/docs/core-concepts/scaling/cpu-isolation



Learn how Aptible effectively manages CPU allocations to maximize performance and reliability

## Overview

Scaling up resources in Aptible directly increases the guaranteed CPU Allocation for a container. However, containers can sometimes burst above their CPU allocation if the underlying infrastructure host has available capacity. For example, if a container is scaled to a 4GB general-purpose container, it would have a 1 vCPU allocation or 100% CPU utilization in our metrics. You may see in your metrics graph that the CPU utilization bursts to higher values, like 150% or higher. This burst capability was allowed because the infrastructure host had excess capacity, which is not guaranteed. At other times, if your CPU metrics are flattening out at a usage of 100%, it likely signifies that the container(s) are being prevented from using more than their allocation because excess capacity is unavailable.

It's important to note that users cannot view the full CPU capacity of the host, so users must consider metric drains to monitor and alert on CPU usage to ensure that app services have adequate CPU allocation. To ensure a higher guaranteed CPU allocation, you must scale your resources.

## Modifying CPU Allocation

The guaranteed CPU Allocation can be increased or decreased by vertical scaling. See: [App Scaling](/docs/core-concepts/scaling/app-scaling) or [Database Scaling](/docs/core-concepts/scaling/database-scaling) for more information on vertical scaling.


# Database Scaling
Source: https://www.aptible.com/docs/core-concepts/scaling/database-scaling

Learn about scaling Databases CPU, RAM, IOPS and throughput

## Overview

Scaling your Databases on Aptible is straightforward and efficient. You can scale Database from the Dashboard, CLI, or Terraform to adjust your database resources like CPU, RAM, IOPS, and throughput, and Aptible ensures appropriate hardware is provisioned. All Database scaling operations are performed with **minimal downtime**, typically less than one minute.

## Vertical Scaling

Scale Databases vertically by changing the size of Containers, i.e., changing the [Memory Limits](/docs/core-concepts/scaling/memory-limits) and [CPU Limits](/docs/core-concepts/scaling/container-profiles). The available sizes are determined by the [Container Profile.](/docs/core-concepts/scaling/container-profiles)

## Horizontal Scaling

While Databases cannot be scaled horizontally by adding more Containers, horizontal scaling can be achieved by setting up database replication and clustering. Refer to [Database Replication and Clustering](/docs/core-concepts/managed-databases/managing-databases/replication-clustering) for more information.

## Disk Scaling

Database Disks can be scaled up to 16384GB. Database Disks can be resized at most once a day and can only be resized up (i.e., you cannot shrink your Database Disk).

Cloud block storage can be expanded in place, but it cannot safely be reduced in place. Shrinking a disk would require the storage provider to know which blocks are safe to discard, which is not reliable for a running cloud volume and could cause data loss.

If you need a smaller Database Disk, migrate the data to a new Database with the smaller target disk size:

* Use dump and restore for PostgreSQL or MySQL.
* Use replication and failover when your Database type and migration requirements support it.

<Note>
  For large Databases, especially those in the many tens of gigabytes or larger, dump and restore can take significant time. If the required migration window is too long, replication followed by a planned cutover may be a better fit because the new Database can catch up before you switch application traffic.
</Note>

Refer to [Supported Databases](/docs/core-concepts/managed-databases/supported-databases/overview) to see whether replication and failover are supported for your Database type.

## IOPS Scaling

Database IOPS can be scaled with no downtime. Database IOPS can only be scaled using the [`aptible db:modify`](/docs/reference/aptible-cli/cli-commands/cli-db-modify) command. Refer to [Database Performance Tuning](/docs/core-concepts/managed-databases/managing-databases/database-tuning#database-iops-performance) for more information.

## Throughput performance

All new Databases are provisioned with GP3 volume, with a default throughput performance of 125MiB/s. This can be scaled up to 1,000MiB/s by contacting [Aptible Support](/docs/how-to-guides/troubleshooting/aptible-support). Refer to [Database Performance Tuning](/docs/core-concepts/managed-databases/managing-databases/database-tuning#database-throughput-performance) for more information.

***

## FAQ

<AccordionGroup>
  <Accordion title="Is there downtime from scaling a Database?">
    Yes, all Database scaling operations are performed with **minimal downtime**, typically less than one minute.
  </Accordion>

  <Accordion title="How do I scale a Database">
    See related guide:

    <Card title="How to scale Databases" icon="book-open-reader" href="https://www.aptible.com/docs/scale-databases" />
  </Accordion>
</AccordionGroup>


# Memory Management
Source: https://www.aptible.com/docs/core-concepts/scaling/memory-limits

Learn how Aptible enforces memory limits to ensure predictable performance

## Overview

Memory limits are enforced through a feature called Memory Management.

When memory management is enabled on your infrastructure and a Container exceeds its memory allocation, the following happens:

1. Aptible sends a log message to your [Log Drains](/docs/core-concepts/observability/logs/log-drains/overview) (this includes [`aptible logs`](/docs/reference/aptible-cli/cli-commands/cli-logs)) indicating that your Container exceeded its memory allocation, and dumps a list of the processes running in your Container for troubleshooting purposes.
2. If there is free memory on the instance, Aptible increases your Container's memory allowance by 10%. This gives your Container a better shot at exiting cleanly.
3. Aptible delivers a `SIGTERM` signal to all the processes in your Container, and gives your Container 10 seconds to exit. If your Container does not exit within 10 seconds, Aptible delivers a `SIGKILL` signal, effectively terminating all the processes in your Container immediately.
4. Aptible triggers [Container Recovery](/docs/core-concepts/architecture/containers/container-recovery) to restart your Container.

The [Metrics](/docs/core-concepts/observability/metrics/overview) you see in the Dashboard are captured every minute. If your Container exceeds its RAM allocation very quickly and then is restarted, **the metrics you see in the Dashboard may not reflect the usage spike**. As such, it's a good idea to refer to your logs as the authoritative source of information to know when you're exceeding your memory allocation. Indeed, whenever your Containers are restarted, Aptible will log this message to all your [Log Drains](/docs/core-concepts/observability/logs/log-drains/overview):

```text theme={null}
container exceeded its memory allocation
```

This message will also be followed by a snapshot of the memory usage of all the processes running in your Container, so you can identify memory hogs more easily.

Here is an example. The column that shows RAM usage is `RSS`, and that usage is expressed in kilobytes.

```text theme={null}
           PID    PPID      VSZ      RSS  STAT    COMMAND
          2688    2625      820       36  S       /usr/lib/erlang/erts-7.3.1/bin/epmd -daemon
          2625     914     1540      936  S       /bin/sh -e /srv/rabbitmq_server-3.5.8/sbin/rabbitmq-server
         13255     914     6248      792  S       /bin/bash
          2792    2708      764       12  S       inet_gethost 4
          2793    2792      764       44  S       inet_gethost 4
          2708    2625  1343560  1044596  S       /usr/lib/erlang/erts-7.3.1/bin/beam.smp [...]
```

## Understanding Memory Utilization

There are two main categories of memory on Linux: RSS and caches.

In Metrics on Aptible, RSS is published as an individual metric, and the sum of RSS + caches (i.e. total memory usage) is published as a separate metric.

It's important to understand the difference between RSS and Caches when optimizing against memory limits.

At a high level, RSS is memory that is allocated and used by your App or Database, and caches represent memory that is used by the operating system (Linux) to make your App or Database faster. In particular, caches are used to accelerate disk access.

If your container approaches its memory limit, the host system will attempt to reclaim some memory from your Container or terminate it if that's not possible. Memory used for caches can usually be reclaimed, whereas anonymous memory and memory-mapped files (RSS) usually cannot.

When monitoring memory usage, you should make sure RSS never approaches the memory limit. Crossing the limit would result in your Containers being restarted. For Databases, you should also usually ensure a decent amount of memory is available to be used for caches by the operating system.

In practice, you should normally ensure RSS does not exceed about \~70% of the memory limit. That said, this advice is very Database dependent: for [PostgreSQL](/docs/core-concepts/managed-databases/supported-databases/postgresql), 30% is a better target, and for [Elasticsearch](/docs/core-concepts/managed-databases/supported-databases/elasticsearch), 50% is a good target.

However, Linux allocates caches very liberally, so don't be surprised if your Container is using a lot of memory for caches. In fact, for a Database, cache usage will often cause your total memory usage to equal 100% of your memory limit: that's expected.

***

## FAQ

<AccordionGroup>
  <Accordion title="What should my app do when it receives a SIGTERM from Aptible?">
    Your app should try and exit gracefully within 10 seconds.

    If your app is processing background work, you should ideally try and push it back to whatever queue it came from.
  </Accordion>

  <Accordion title="How do I know the memory usage for a Container?">
    See [Metrics](/docs/core-concepts/observability/metrics/overview).
  </Accordion>

  <Accordion title="How do I know the memory limit for a Container?">
    You can view the current memory limit for any Container by looking at the Container's [Metrics](/docs/core-concepts/observability/metrics/overview) in your Dashboard: the memory limit is listed right next to your current usage.

    Additionally, Aptible sets the `APTIBLE_CONTAINER_SIZE` environment variable when starting your Containers. This indicates your Container's memory limit, in MB.
  </Accordion>

  <Accordion title="How do I increase the memory limit for a Container?">
    See [Scaling](/docs/core-concepts/scaling/overview).
  </Accordion>
</AccordionGroup>


# Scaling
Source: https://www.aptible.com/docs/core-concepts/scaling/overview

Learn more about scaling on-demand without worrying about any underlying configurations or capacity availability

## Overview

The Aptible platform simplifies the process of on-demand scaling, removing the complexities of underlying configurations and capacity considerations. With customizable container profiles, Aptible enables precise resource allocation, optimizing both performance and cost-efficiency.

## Learn more about scaling resources on Aptible

<CardGroup>
  <Card title="App Scaling" icon="book" href="https://www.aptible.com/docs/core-concepts/scaling/app-scaling" />

  <Card title="Database Scaling" icon="book" href="https://www.aptible.com/docs/core-concepts/scaling/database-scaling" />

  <Card title="Container Profiles" icon="book" href="https://www.aptible.com/docs/core-concepts/scaling/container-profiles" />

  <Card title="CPU Allocation" icon="book" href="https://www.aptible.com/docs/core-concepts/scaling/cpu-isolation" />

  <Card title="Memory Management" icon="book" href="https://www.aptible.com/docs/core-concepts/scaling/memory-limits" />

  <Card title="Container Right-Sizing Recommendations" icon="book" href="https://www.aptible.com/docs/core-concepts/scaling/container-right-sizing-recommendations" />
</CardGroup>

## FAQ

<AccordionGroup>
  <Accordion title="Does Aptible offer autoscaling functionality?">
    Yes, read more in the [App Scaling page](/docs/core-concepts/scaling/app-scaling)
  </Accordion>
</AccordionGroup>


# Roles & Permissions
Source: https://www.aptible.com/docs/core-concepts/security-compliance/access-permissions



# Organization

Aptible organizations represent an administrative domain consisting of users and resources.

# Users

Users represent individuals or robots with access to your organization. A user's assigned roles determine their permissions and what they can access Aptible. Manage users in the Aptible dashboard by navigating to Settings > Members.

<Frame>
  <img alt="Managing Members" />
</Frame>

# Roles

Use roles to define users' access in your Aptible organization. Manage roles in the Aptible Dashboard by navigating to Settings > Roles.

<Frame>
  <img alt="Role Management" />
</Frame>

## Types of Roles

### Built in roles

#### Account Owners

The Account Owners Role is one of the built-in roles in your organization that grants the following:

* admin access to all resources
* access to [billing information](/docs/core-concepts/billing-payments) such as invoices, projections, plans, and contracts
* the ability to invite users
* the ability to manage all Roles
* the ability to remove all users from the organization

#### Aptible Deploy Owners

The Deploy Owners Role is one of the built-in roles in your organization that grants the following:

* admin access to all resources
* the ability to invite users
* the ability to manage the Aptible Deploy Owners Role and Custom Roles
* the ability to remove users within Aptible Deploy Owners Role and/or Custom Roles from the organization

### Billing-Only

The Billing-Only Role is one of the built-in roles in your organization that grants the following:

* access to [billing information](/docs/core-concepts/billing-payments) such as invoices, projections, plans, payment methods, and contracts
* the ability to manage billing-related tasks

This role does not grant access to any Aptible resources such as apps, databases, or environments.

Only Account Owners can add or remove users from the Billing-Only Role. Users in this role cannot invite others or modify role assignments.

#### Activity Log Viewer

The Activity Log Viewer Role is one of the built-in roles in your organization that grants the following:

* read-only access to all [Activity](/docs/core-concepts/observability/activity/overview) for your organization

This role is designed for users whose sole purpose is activity log access — for example, a dedicated service user for a SIEM integration.

### Role Admin

Members of any role — built-in or custom — can be granted Role Admin permissions for that role. A Role Admin has the additional abililty to add and remove members of the roles of which they are role admins

### Custom Roles

Use custom roles to configure which Aptible environments a user can access and what permissions they have within those environments. Aptible provides many permission types so you can fine-tune user access.

Since roles define what environments users can access, we highly recommend using multiple environments and roles to ensure you are granting access based on [the least-privilege principle](https://csrc.nist.gov/glossary/term/least_privilege).

<Frame>
  <img alt="Edit role admins" />
</Frame>

#### Custom Role Members

Custom Role Members have access to resources as defined by the permission types of their custom role.

#### Custom Role Permissions

Manage custom role permission types in the Aptible Dashboard by navigating to Settings > Roles. Select the respective role, navigate to Environments, and grant the desired permissions for the separate environments.

<Frame>
  <img alt="Edit permissions" />
</Frame>

#### Read Permissions

Assign one of the following permissions to give users read permission in a specific environment:

* **Basic Visibility**: can read general information about all resources
* **Full Visibility (formerly Read)**: can read general information about all resources and app configurations

#### Write Permissions

To give users write permission to a given environment, you can assign the following permissions:

* **Environment Admin** (formerly Write): can perform all actions listed below within the environment
* **Deployment**: can create and deploy resources
* **Destruction**: can destroy resources
* **Ops**: can create and manage log and metric drains and restart and scale apps and databases
* **Sensitive Access**:  can view and manage sensitive values such as app configurations, database credentials, and endpoint certificates
* **Tunnel**: can tunnel into databases but cannot view database credentials

<Tip> Provide read-only database access by granting the Tunnel permission without the Sensitive Access permission. Use this to manage read-only database access within the database itself.</Tip>

#### Full Permission Type Matrix

This matrix describes the required permission (header) for actions available for a given resource(left column).

|                                | Environment Admin | Full Visibility | Deployment | Destruction | Ops | Sensitive Access | Tunnel |
| :----------------------------: | :---------------: | :-------------: | :--------: | :---------: | :-: | :--------------: | ------ |
|           Environment          |        ---        |       ---       |     ---    |     ---     | --- |        ---       | ---    |
|           Deprovision          |         ✔         |                 |            |      ✔      |     |                  |        |
|             Rename             |         ✔         |                 |            |             |     |                  |        |
| Manage Backup Retention Policy |         ✔         |                 |            |             |     |                  |        |
|              Apps              | Environment Admin | Full Visibility | Deployment | Destruction | Ops | Sensitive Access | Tunnel |
|             Create             |         ✔         |                 |      ✔     |             |     |         ✔        |        |
|           Deprovision          |         ✔         |                 |            |      ✔      |     |                  |        |
|       Read Configuration       |         ✔         |        ✔        |            |             |     |         ✔        |        |
|            Configure           |         ✔         |                 |      ✔     |             |     |         ✔        |        |
|             Rename             |         ✔         |                 |      ✔     |             |     |                  |        |
|             Deploy             |         ✔         |                 |      ✔     |             |     |                  |        |
|             Rebuild            |         ✔         |                 |      ✔     |             |     |                  |        |
|              Scale             |         ✔         |                 |      ✔     |             |  ✔  |                  |        |
|             Restart            |         ✔         |                 |      ✔     |             |  ✔  |                  |        |
|        Create Endpoints        |         ✔         |                 |      ✔     |             |     |                  |        |
|      Deprovision Endpoints     |         ✔         |                 |            |      ✔      |     |                  |        |
|           Stream Logs          |         ✔         |                 |      ✔     |             |  ✔  |                  |        |
|           SSH/Execute          |         ✔         |                 |            |             |     |         ✔        |        |
|            Databases           | Environment Admin | Full Visibility | Deployment | Destruction | Ops | Sensitive Access | Tunnel |
|             Create             |         ✔         |                 |      ✔     |             |     |                  |        |
|           Deprovision          |         ✔         |                 |            |      ✔      |     |                  |        |
|        Read Credentials        |         ✔         |                 |            |             |     |         ✔        |        |
|         Create Backups         |         ✔         |                 |      ✔     |             |  ✔  |                  |        |
|         Restore Backups        |         ✔         |                 |      ✔     |             |     |                  |        |
|         Delete Backups         |         ✔         |                 |            |      ✔      |     |                  |        |
|             Rename             |         ✔         |                 |      ✔     |             |     |                  |        |
|    Restart / Reload / Modify   |         ✔         |                 |      ✔     |             |  ✔  |                  |        |
|         Create Replicas        |         ✔         |                 |      ✔     |             |     |                  |        |
|         Unlink Replicas        |         ✔         |                 |            |      ✔      |     |                  |        |
|        Create Endpoints        |         ✔         |                 |      ✔     |             |     |                  |        |
|      Deprovision Endpoints     |         ✔         |                 |            |      ✔      |     |                  |        |
|         Create Tunnels         |         ✔         |                 |            |             |     |                  | ✔      |
|           Stream Logs          |         ✔         |                 |      ✔     |             |  ✔  |                  |        |
|      Log and Metric Drains     | Environment Admin | Full Visibility | Deployment | Destruction | Ops | Sensitive Access | Tunnel |
|             Create             |         ✔         |                 |      ✔     |             |  ✔  |                  |        |
|           Deprovision          |         ✔         |                 |      ✔     |      ✔      |  ✔  |                  |        |
|        SSL Certificates        | Environment Admin | Full Visibility | Deployment | Destruction | Ops | Sensitive Access | Tunnel |
|             Create             |         ✔         |                 |            |             |     |         ✔        |        |
|        Persistent Disks        | Environment Admin | Full Visibility | Deployment | Destruction | Ops | Sensitive Access | Tunnel |
|              Read              |         ✔         |        ✔        |            |             |     |                  |        |
|             Create             |         ✔         |                 |      ✔     |             |     |                  |        |
|         Resize / Modify        |         ✔         |                 |      ✔     |             |  ✔  |                  |        |
|             Destroy            |         ✔         |                 |            |      ✔      |     |                  |        |
|       Attach to a Service      |         ✔         |                 |      ✔     |             |     |                  |        |
|      Detach from a Service     |         ✔         |                 |      ✔     |      ✔      |     |                  |        |

Creating a Persistent Disk and attaching it to a Service require the **Deployment** permission. Resizing or modifying a disk requires the **Deployment** or **Ops** permission, and detaching a disk from a Service requires the **Deployment** or **Destruction** permission. Deleting a disk requires the **Destruction** permission. These are the same environment-scoped permissions used to manage Apps and Databases. No special or privileged access is required.


# Password Authentication
Source: https://www.aptible.com/docs/core-concepts/security-compliance/authentication/password-authentication



Users can use password authentication as one of the authentication methods to access Aptible resources via the Dashboard and CLI.

# Requirements

Passwords must:

1. be at least 10 characters, and no more than 72 characters.
2. contain at least one uppercase letter (A-Z).
3. contain at least one lowercase letter (a-z).
4. include at least one digit or special character (^0-9!@#\$%^&\*()).

Aptible uses [Have I Been Pwned](https://haveibeenpwned.com) to implement a denylist of known compromised passwords.

# Account Lockout Policies

Aptible locks out users if there are:

1. 10 failed attempts in 1 minute result in a 1-minute lockout
2. 20 failed attempts in 1 hour result in a 1-hour lockout
3. 40 failed attempts in 1 day result in a 1-day lockout

Aptible monitors for repeat unsuccessful login attempts and notifies customers of any such repeat attempts that may signal an account takeover attempt. For granular control over login data, such as reviewing every login from your team members, set up [SSO](/docs/core-concepts/security-compliance/authentication/sso) using a SAML provider, and [require SSO](/docs/core-concepts/security-compliance/authentication/sso#require-sso-for-access) for accessing Aptible.

# 2-Factor Authentication (2FA)

Regardless of SSO usage or requirements, Aptible strongly recommends using 2FA to protect your Aptible account and all other sensitive internet accounts.

# 2-Factor Authentication With SSO

When SSO is enabled for your organization, it is not possible to both require that members of your organization have 2-Factor Authentication enabled, and use SSO at the same time.  However, you can require that they login with SSO in order to access your organization’s resources and enforce rules such as requiring 2FA via your SSO provider.

If you’re interested in enabling SSO for your organization contact [Aptible Support](https://app.aptible.com/support).

## Enrollment

Users can enable 2FA Authentication in the Dashboard by navigating to Settings > Security Settings > Configure 2FA.

## Supported Protocols

Aptible supports:

1. software second factors via the TOTP protocol. We recommend using [Google Authenticator](https://support.google.com/accounts/answer/1066447?hl=en) as your TOTP client
2. hardware second factors via the FIDO protocol.

## Scope

When enabled, 2FA protects access to your Aptible account via the Dashboard, CLI, and API. 2FA does not restrict Git pushes - these are still authenticated with [SSH Public Keys](/docs/core-concepts/security-compliance/authentication/ssh-keys). Sometimes, you may not push code with your user credentials, for example, if you deploy with a CI service such as Travis or Circle that performs all deploys via a robot user. If so, we encourage you to remove SSH keys from your Aptible user account.

Aptible 2FA protects logins, not individual requests. Making authenticated requests to the Aptible API is a two-step process:

1. generate an access token using your credentials
2. use that access token to make requests

2FA protects the first step. Once you have an access token, you can make as many requests as you want to the API until that token expires or is revoked.

## Recovering Account Access

Account owners can [reset 2FA for all other users](/docs/how-to-guides/platform-guides/reset-aptible-2fa), including other account owners, but cannot reset their own 2FA.

## Auditing

[Organization](/docs/core-concepts/security-compliance/access-permissions) administrators can audit 2FA enrollment via the Dashboard by navigating to Settings > Members.


# Provisioning (SCIM)
Source: https://www.aptible.com/docs/core-concepts/security-compliance/authentication/scim

Learn about configuring Cross-domain Identity Management (SCIM) on Aptible

<Frame>
  <img alt="" />
</Frame>

## Overview

Aptible has implemented **SCIM 2.0** (System for Cross-domain Identity Management) to streamline the management of user identities across various systems. This implementation adheres closely to [RFC 7643](https://datatracker.ietf.org/doc/html/rfc7643), ensuring standardized communication and data exchange. SCIM 2.0 simplifies provisioning by automating the processes for creating, updating, and deactivating user accounts and managing roles within your organization. By integrating SCIM, Aptible enhances your ability to manage user data efficiently and securely across different platforms.

## How-to Guides

We offer detailed guides to help you set up provisioning with your Identity Provider (IdP). These guides cover the most commonly used providers:

* [Aptible Provisioning with Okta](/docs/how-to-guides/platform-guides/scim-okta-guide)
* [Aptible Provisioning with Entra ID (formerly Azure AD)](/docs/how-to-guides/platform-guides/scim-entra-guide)

These resources will walk you through the steps necessary to integrate SCIM with your preferred provider, ensuring a seamless and secure setup.

## Provisioning FAQ

### How Does SCIM Work?

SCIM (System for Cross-domain Identity Management) is a protocol designed to simplify user identity management across various systems. It enables automated processes for creating, updating, and deactivating user accounts. The main components of SCIM include:

1. **User Provisioning**: Automates the creation, update, and deactivation of user accounts.
2. **Group Management**: Manages roles (referred to as "Groups" in SCIM) and permissions for users.
3. **Attribute Mapping**: Synchronizes user attributes consistently across systems.
4. **Secure Token Exchange**: Utilizes OAuth bearer tokens for secure authentication and authorization of SCIM API calls.

### How long is a SCIM token valid for Aptible?

A SCIM token is valid for one year. After the year, if it expires, you will receive an error in your IDP indicating that your token is invalid.

<img alt="" />

### Aptible Does Not Seem to Support Groups but Roles Instead. How Does That Work with SCIM?

Aptible leverages **Roles** instead of **Groups**. Despite this, the functionality is similar, and SCIM Groups are mapped to Aptible Roles. This mapping ensures that permissions and access controls are maintained consistently.

### What Parts of the SCIM Specifications Aren't Included in Aptible's SCIM Implementation?

Aptible aims to continually enhance support for SCIM protocol components. However, some parts are not currently implemented:

1. **Search Queries Using POST**: Searching for resources using POST requests is not supported.
2. **Bulk Operations**: Bulk operations for creating, updating, or deleting resources are not supported.
3. **/Me Endpoint**: Accessing the authenticated user's information via the /Me endpoint is not supported.
4. **/Schemas Endpoint**: Retrieving metadata about resource types via the /Schemas endpoint is not supported.
5. **/ServiceProviderConfig Endpoint**: Accessing service provider configuration details via the /ServiceProviderConfig endpoint is not supported.
6. **/ResourceTypes Endpoint**: Listing supported resource types via the /ResourceTypes endpoint is not supported.

### How Much Support is Required for Filtering Results?

While the SCIM protocol supports extensive filtering capabilities, Aptible's primary use case for filtering is straightforward. Aptible checks if a newly created user or group exists in your application based on a matching identifier. Therefore, supporting the `eq` (equals) operator is sufficient.

### I am connecting to an account with users who are already set up. How Does SCIM Behave?

When integrating SCIM with an account that already has users, SCIM will:

1. **Match Existing Users**: It will identify existing users based on their unique identifier (email) and update their information if needed rather than creating new accounts.
2. **Create New Users**: If a user does not exist, SCIM will create a new account with the specified attributes and assign the default role (referred to as "Group" in SCIM).
3. **Role Assignments**: Newly created users will receive the default role. Existing role assignments for users already in the system will not be altered. SCIM will not remove or change existing roles.

### How Do I Correctly Disable SCIM and Retain a Clean Data Set?

To disable SCIM and manage the associated data within your Aptible Organization:

1. **Retaining Created Roles and Users**: If you want to keep the roles and users created by SCIM, simply disable SCIM as an Aptible Organization owner. This action will remove the SCIM association but leave the created users and roles intact.

2. **Removing SCIM-Created Data**: If you wish to remove users and roles created by SCIM, begin by unassigning any users and roles in your Identity Provider (IDP) that were created via SCIM. This action will soft delete these objects from your Aptible Organization. After all assignments have been removed, you can then deactivate the SCIM integration, ensuring a clean removal of all associated data.

### What authentication methods are supported by the Aptible SCIM API?

Aptible's SCIM implementation uses the **OAuth 2.0 Authorization Code grant flow** for authentication. It does not support the Client Credentials or Resource Owner Password Credentials grant flows. The Authorization Code grant flow is preferred for SaaS and cloud integrations due to its enhanced security.

### What is Supported by Aptible?

Aptible's SCIM implementation includes the following features:

1. **User Management**: Automates the creation, update, and deactivation of user accounts.
2. **Role Management (Groups)**: This function assigns newly created users the specified default role (referred to as "Groups" in SCIM).
3. **Attribute Synchronization**: Ensures user attributes are consistently synchronized across systems.
4. **Secure Authentication**: Uses OAuth bearer tokens for secure SCIM API calls.
5. **Email as Unique Identifier**: Uses email as the unique identifier for validating and matching user data.

### I see you have guides for Identity Providers, but mine is not included. What should I do?

Aptible follows the SCIM 2.0 guidelines, so you should be able to integrate with us as long as the expected attributes are correctly mapped.

> 📘 Note We cannot guarantee the operation of an integration that has not been tested by Aptible. Proceeding with an untested integration is at your own risk.

**Required Attributes:**

* **`userName`**: The unique identifier for the user, essential for correct user identification.
* **`displayName`**: The name displayed for the user, typically their full name; used in interfaces and communications.
* **`active`**: Indicates whether the user is active (`true`) or inactive (`false`); crucial for managing user access.
* **`externalId`**: A unique identifier used to correlate the user across different systems; helps maintain consistency and data integrity.

**Optional but recommended Attributes:**

* **`givenName`**: The user's first name; can be used as an alternative in conjunction with familyName to `displayName`.
* **`familyName`**: The user's last name; also serves as an alternative in conjunction with givenName to `displayName`.

**Supported Operations**

* **Sorting**: Supports sorting by `userName`, `id`, `meta.created`, and `meta.lastModified`.
* **Pagination**: Supports `startIndex` and `count` for controlled data fetching.
* **Filtering**: Supports basic filtering; currently limited to the `userName` attribute.

By ensuring these attributes are mapped correctly, your Identity Provider should integrate seamlessly with our system.

### Additional Notes

* SCIM operations ensure that existing user data and role assignments are not disrupted unless explicitly updated.
* Users will only be removed if they are disassociated from SCIM on the IDP side; they will not be removed by simply disconnecting SCIM, ensuring safe user account management.
* Integrating SCIM with Aptible allows for efficient and secure synchronization of user data across your identity management systems.

For more detailed instructions on setting up SCIM with Aptible, please refer to the [Aptible SCIM documentation](#) or contact support for assistance.


# SSH Keys
Source: https://www.aptible.com/docs/core-concepts/security-compliance/authentication/ssh-keys

Learn about using SSH Keys to authenticate with Aptible

## Overview

Public Key Authentication is a secure method for authentication, and how Aptible authenticates deployments initiated by pushing to an [App](/docs/core-concepts/apps/overview)'s [Git Remote](/docs/how-to-guides/app-guides/deploy-from-git#git-remote). You must provide a public SSH key to set up Public Key Authentication.

<Warning> If SSO is enabled for your Aptible organization, attempts to use the git remote will return an `App not found or not accessible` error. Users must be added to the [allowlist](/docs/core-concepts/security-compliance/authentication/sso#exempt-users-from-sso-requirement) to access your Organization's resources via Git. </Warning>

## Supported SSH Key Types

Aptible supports the following SSH key types:

* ssh-rsa

* ssh-ed25519

* ssh-dss

## Adding/Managing SSH Keys

<Frame>
  <img alt="" />
</Frame>

If you [don't already have an SSH Public Key](https://docs.github.com/en/authentication/connecting-to-github-with-ssh/checking-for-existing-ssh-keys), generate a new SSH key using this command:

```
ssh-keygen -t ed25519 -C "your_email@example.com"
```

If you are using a legacy system that doesn't support the Ed25519 algorithm, use the following:

```
shell ssh-keygen -t rsa -b 4096 -C "you@example.com"
```

Once you have generated your SSH key, follow these steps:

1. In the Aptible dashboard, select the Settings option on the bottom left.

2. Select the SSH Keys option under Account Settings.

3. Reconfirm your credentials by entering your password on the page that appears.

4. Follow the instructions for copying your Public SSH Key in Step 1 listed on the page.

5. Paste your Public SSH Key in the text box located in Step 2 listed on the page.

# Featured Troubleshooting Guides

<Card title="git Push Permission Denied" icon="book-open-reader" href="https://www.aptible.com/docs/permission-denied-git-push" />


# Single Sign-On (SSO)
Source: https://www.aptible.com/docs/core-concepts/security-compliance/authentication/sso



<Frame>
  <img alt="" />
</Frame>

# Overview

<Info> SSO/SAML is only available on [Production and Enterprise](https://www.aptible.com/pricing)[ plans.](https://www.aptible.com/pricing)</Info>

Aptible provides Single Sign On (SSO) to an [organization's](/docs/core-concepts/security-compliance/access-permissions) resources through a separate, single authentication service, empowering customers to manage Aptible users from their primary SSO provider or Identity Provider (IdP).

Aptible supports the industry-standard SAML 2.0 protocol for using an external provider. Most SSO Providers support SAML, including Okta and Google's GSuite. SAML provides a secure method to transfer identity and authentication information between the SSO provider and Aptible.

Each organization may have only one SSO provider configured. Many SSO providers allow for federation with other SSO providers using SAML. For example, allowing Google GSuite to provide login to Okta. If you need to support multiple SSO providers, you can use federation to enable login from the other providers to the one configured with Aptible.

<Card title="How to setup Single Sign-On (SSO)" icon="book-open-reader" href="https://www.aptible.com/docs/sso-setup" />

## Organization Login ID

When you complete [Single Sign On Provider Setup](/docs/how-to-guides/platform-guides/setup-sso), your [organization's](/docs/core-concepts/security-compliance/access-permissions) users can use the SSO link on the [SSO login page](https://app.aptible.com/sso) to begin using the configured SSO provider. They must enter an ID unique to your organization to indicate which organization they want to access.

That ID defaults to a randomly assigned unique identifier. [Account owners](/docs/core-concepts/security-compliance/access-permissions) may keep that identifier or set an easier-to-remember one on the SSO settings page. Your organization's primary email domain or company name makes a good choice. That identifier is to make login easier for users.

<Warning> Do not change your SSO provider configuration after changing the Login ID. The URLs entered in your SSO provider configuration should continue to use the long, unique identifier initially assigned to your organization. Changing the SSO provider configuration to use the short, human-memorable identifier will break the SSO integration until you restore the original URLs. </Warning>

You will have to distribute the ID to your users so they can enter it when needed. To simplify this, you can embed the ID directly in the URL. For example, `https://app.aptible.com/sso/example_id`. Users can then bookmark or link to that URL to bypass the need to enter the ID manually. You can start the login process without knowing your organization's unique ID if your SSO provider has an application "dashboard" or listing.

## Require SSO for Access

When `Require SSO for Access` is enabled, Users can only access their [organization's](/docs/core-concepts/security-compliance/access-permissions) resources by using your [configured SAML provider](/docs/how-to-guides/platform-guides/setup-sso) to authenticate with Aptible. This setting aids in enforcing restrictions within the SSO provider, such as password rotation or using specific second factors.

Require SSO for Access will prevent users from doing the following:

* [Users](/docs/core-concepts/security-compliance/access-permissions) cannot log in using the Aptible credentials and still access the organization's resources.
* [Users](/docs/core-concepts/security-compliance/access-permissions) cannot use their SSH key to access the git remote.

Manage the Require SSO for Access setting in the Aptible Dashboard by selecting Settings > Single Sign-On.

<Warning> Before enforcing SSO, we recommend notifying all the users in your organization. SSO will be the only way to access your organization at that point. </Warning>

## CLI Token for SSO

To use the [Aptible CLI](/docs/reference/aptible-cli/cli-commands/overview) with Require SSO for Access enabled, users must:

1. Generate an SSO token.
   1. In the Aptible Dashboard, select the user's profile on the top right and then "CLI SSO Token," which will bring you to the [CLI SSO Token settings page.](https://app.aptible.com/settings/tokens)
2. Provide the token to the CLI via the [`aptible login --sso $SSO_TOKEN`](/docs/reference/aptible-cli/cli-commands/cli-login) command.

### Invalidating CLI Token for SSO

1. Tokens will be automatically invalidated once the selected duration elapses.
2. Generating a new token will not invalidate older tokens.
3. To invalidate the token generated during your current session, use the "Logout" button on the bottom left of any page.
4. To invalidate tokens generated during other sessions, except your current session, navigate to Settings > Security > "Log out all sessions"

### Controlling CLI Token Lifetime

To limit how long CLI tokens remain valid when using SSO:

1. **Require SSO for all users** — Enable [Require SSO for Access](#require-sso-for-access) (described above).
2. **Configure session duration in your Identity Provider** — Set a shorter max session duration in your IdP (e.g., Google Workspace). This is where the limit is enforced.

The token generated for Aptible will be limited to the max session duration configured in your Identity Provider, even if a user selects a longer duration in the Aptible dashboard

## Exempt Users from SSO Requirement

Users exempted from the Require SSO for Access setting can log in using Aptible credentials and access the organization's resources. Users can be exempt from this setting in two ways:

* users with an Account Owner role are always exempt from this setting
* users added to the SSO Bypass Allowlist

The SSO Bypass Allowlist will only appear in the SSO settings once `Require SSO for Access` is enabled.

<Note> Account Owners and users on the SSO Bypass Allowlist can generate CLI tokens directly through Aptible (via username/password login) even when Require SSO is enabled. These users may create tokens with a lifetime of up to 7 days. There is no mechanism to reduce this 7-day limit at the organization level. To enforce shorter token lifetimes, we recommend limiting the number of users granted Account Owner access. </Note>

We recommend restricting the number of Users exempt from the `Require SSO for Access` settings, but there are some use cases where it is necessary; some examples include:

* to allow [users](/docs/core-concepts/security-compliance/access-permissions) to use their SSH key to access the git remote
* to give contributors (e.g., consultants or contractors) access to your Aptible account without giving them an account in your SSO provider
* to grant "robot" accounts access to your Aptible account to be used in Continuous Integration/Continuous Deployment systems

### Users in Multiple Organizations

Users can be members of multiple organizations. If a user logs in with Aptible username and password (rather than SSO), they can create tokens with a lifetime of up to 7 days. However, without Account Owner access in a given organization, those tokens will not grant access to that organization's resources. So even if a user can create longer-lived tokens via password login, those tokens will not provide access to resources in an organization where Require SSO is enabled.


# HIPAA
Source: https://www.aptible.com/docs/core-concepts/security-compliance/compliance-frameworks/hipaa

Learn about achieving HIPAA compliance on Aptible

<Check>
  <Tooltip>Compliance-Ready</Tooltip>
</Check>

# Overview

Aptible’s story began with a focus on serving digital health companies. As a result, the Aptible platform was designed with HIPAA compliance in mind. It automates and enforces all the necessary infrastructure security and compliance controls, ensuring the safe storage and processing of HIPAA-protected health information and more.

# Achieving HIPAA on Aptible

<Steps>
  <Step title="Provision a Dedicated Stack to run your resources">
    <Info> Dedicated Stacks are available on [Production and Enterprise plans](https://www.aptible.com/pricing).</Info>
    Dedicated Stacks live on isolated infrastructure and are designed to support deploying resources with higher requirements— such as HIPAA. Aptible automates and enforces **100%** of the necessary infrastructure security and compliance controls for HIPAA compliance.
  </Step>

  <Step title="Execute a HIPAA BAA with Aptible">
    When you request your first dedicated stack, an Aptible team member will reach out to coordinate the execution of a Business Associate Agreement (BAA).
  </Step>

  <Step title="Show off your compliance" icon="party-horn">
    <Frame>
      <img alt="" />
    </Frame>

    The Security & Compliance Dashboard and reporting serves as a great resource for showing off HIPAA compliance. When a Dedicated Stack is provisioned, the HIPAA required controls will show as 100% - by default.

    <Accordion title="Understanding the HIPAA Readiness Score">
      The Health Insurance Portability and Accountability Act of 1996 (HIPAA) is a federal law that dictates US standards to protect sensitive patient health information from being disclosed without the patient’s consent or knowledge. The [US Department of Health and Human Services (HHS)](https://www.hhs.gov/hipaa/index.html) issued the HIPAA Privacy Rule to implement the requirements of HIPAA. The HIPAA Security Rule protects a subset of information covered by the Privacy Rule.

      The Aptible Security & Compliance Dashboard provides a HIPAA readiness score based on controls required for meeting the minimum standards of the regulation, labeled HIPAA Required, as well as addressable controls that are not required to meet the specifications of the regulation but are recommended as a good security practice, labeled HIPAA Addressable.

      ## HIPAA Required Score

      HIPAA prescribes certain implementation specifications as “required, “meaning you must implement the control to meet the regulation requirements. An example of such a specification is 164.308(a)(7)(ii)(A), requiring implemented procedures to create and maintain retrievable exact copies of ePHI. You can meet this specification with Aptible’s [automated daily backup creation and retention policy](/docs/core-concepts/managed-databases/managing-databases/database-backups).

      The HIPAA Required score gives you a binary indicator of whether or not you’re meeting the required specifications under the regulation. By default, all resources hosted on a [Dedicated Stack](/docs/core-concepts/architecture/stacks) meet the required specifications of HIPAA, so if you plan on processing ePHI, it’s a good idea to host your containers on a Dedicated Stack from day 1.

      ## HIPAA Addressable Score

      The HHS developed the concept of “addressable implementation specifications” to provide covered entities and business associates additional flexibility regarding compliance with HIPAA. In meeting standards that contain addressable implementation specifications, a covered entity or business associate will do one of the following for each addressable specification:

      * Implement the addressable implementation specifications;
      * Implement one or more alternative security measures to accomplish the same purpose;
      * Not implement either an addressable implementation specification or an alternative.

      The HIPAA Addressable score tells you what percentage of infrastructure controls you have implemented successfully to meet relevant addressable specifications per HIPAA guidelines.
    </Accordion>

    Add a `Secured by Aptible` badge and link to the Secured by Aptible page to show all the security & compliance controls implemented..

    <Frame>
      <img alt="" />
    </Frame>
  </Step>
</Steps>

# Keep Reading

<CardGroup>
  <Card title="Read HIPAA Compliance Guide for Startups" icon="book" href="https://www.aptible.com/blog/hipaa-compliance-guide-for-startups">
    Gain a deeper understanding of HIPAA compliance
  </Card>

  <Card title="Explore HITRUST" icon="book" href="https://www.aptible.com/docs/core-concepts/security-compliance/compliance-frameworks/hitrust">
    Learn why Aptible is the leading platform for achieving HITRUST
  </Card>
</CardGroup>

***

# FAQ

<AccordionGroup>
  <Accordion title="How much does it cost to get started with HIPAA Compliance on Aptible?">
    To begin with HIPAA compliance on Aptible, the Production plan is required, priced at \$499 per month.

    This plan includes one dedicated stack, ensuring the necessary isolation and guardrails for HIPAA requirements. Additional resources are billed on demand, with initial costs typically ranging between 200.00 USD to 500.00 USD.

    Additionally, Aptible offers a Startup Program that provides monthly credits over the first six months.

    [For more details, refer to the Aptible Pricing Page.](https://www.aptible.com/pricing)
  </Accordion>
</AccordionGroup>


# HITRUST
Source: https://www.aptible.com/docs/core-concepts/security-compliance/compliance-frameworks/hitrust

Learn about achieving HITRUST compliance on Aptible

<Check>
  Compliance Fast-Track
</Check>

# Overview

Aptible’s story began with a focus on serving digital health companies. As a result, the Aptible platform was designed with high compliance in mind. It automates and enforces all the necessary infrastructure security and compliance controls, ensuring the safe storage and processing of PHI and more.

# Achieving HITRUST on Aptible

<Steps>
  <Step title="Provision a Dedicated Stack to run your resources">
    <Info>
      Dedicated Stacks are available on [Production and Enterprise plans](https://www.aptible.com/pricing).
    </Info>

    Dedicated Stacks live on isolated infrastructure and are designed to support deploying resources with higher requirements— such as HIPAA and HITRUST. Aptible automates and enforces majority of the necessary infrastructure security and compliance controls for HITRUST compliance. When you request your first dedicated stack, an Aptible team member will also reach out to coordinate the execution of a HIPAA Business Associate Agreement (BAA).
  </Step>

  <Step title="Review the Security & Compliance Dashboard and implement HITRUST required controls">
    <Frame>
      <img alt="" />
    </Frame>

    The Security & Compliance Dashboard serves as a great resource for showing off compliance. When a Dedicated Stack is provisioned, most HITRUST controls will show as complete by default, the remaining controls will show as needing attention.

    <Accordion title="Understanding the HITRUST Readiness Score">
      The HITRUST Common Security Framework (CSF) Certification is a compliance framework based on ISO/IEC 27001. It integrates HIPAA, HITECH, and a variety of other state, local, and industry frameworks and best practices. Independent assessors award this certification when they find that an organization has achieved certain maturity levels in implementing the required HITRUST CSF controls.

      HITRUST CSF is unique because it allows customers to inherit security controls from the infrastructure they host their resources on if the infrastructure provider is also HITRUST CSF certified, enabling you to save time and resources when you begin your certification process. Aptible is HITRUST certified, meaning you can fully inherit up to 30% of security controls implemented and managed by Aptible and partially inherit up to 50% of security controls.

      The Aptible Security & Compliance Dashboard provides a HITRUST readiness score based on controls required for meeting the standards of HITRUST CSF regulation. The HITRUST score tells you what percentage of infrastructure controls you have successfully implemented to meet relevant HITRUST guidelines.
    </Accordion>
  </Step>

  <Step title="Request HITRUST Inhertiance from Aptible">
    Aptible is HITRUST CSF Certified. If you are pursuing your own HITRUST CSF Certification, you may request that Aptible assessment scores be incorporated into your own assessment. This process is referred to as HITRUST Inheritance.

    While it varies per customer, approximately 30%-40% of controls can be fully inherited, and about 20%-30% of controls can be partially inherited.

    <Card title="How to request HITRUST Inhertiance from Aptible" icon="book-open-reader" href="https://www.aptible.com/docs/how-to-guides/platform-guides/navigate-hitrust#how-to-request-hitrust-inhertiance" />
  </Step>

  <Step title="Show off your compliance" icon="party-horn">
    Use the Security & Compliance Dashboard to prove your compliance and show off with a `Secured by Aptible` badge

    <Frame>
      <img alt="" />
    </Frame>
  </Step>
</Steps>

## Related Resources

* [HITRUST Shared Responsibility Matrix](https://hitrustalliance.net/shared-responsibility-matrices) - To see Aptible's shared responsibility matrix
* [Aptible's Trust Center](https://trust.aptible.com/) - To see Aptible's HITRUST certification, reports, and assessment


# PCI DSS
Source: https://www.aptible.com/docs/core-concepts/security-compliance/compliance-frameworks/pci

Learn about achieving PCI DSS compliance on Aptible

<Check>
  <Tooltip>Compliance Fast-Track</Tooltip>
</Check>

# Overview

Aptible’s platform is designed to help businesses meet the strictest security and compliance requirements. With a heritage rooted in supporting security-conscious industries, Aptible automates and enforces critical infrastructure security and compliance controls required for PCI DSS compliance, enabling service providers to securely handle and process payment card data.

# Achieving PCI DSS on Aptible

<Steps>
  <Step title="Provision a Dedicated Stack to run your resources">
    <Info> Dedicated Stacks are available on [Production and Enterprise plans](https://www.aptible.com/pricing).</Info>
    [Dedicated Stacks](https://www.aptible.com/docs/core-concepts/architecture/stacks#stacks) live on isolated infrastructure and are designed to support deploying resources with stringent requirements like PCI DSS. Aptible automates and enforces **100%** of the necessary infrastructure security and compliance controls for PCI DSS compliance.
  </Step>

  <Step title="Review Aptible’s PCI DSS for Service Providers Level 2 attestation">
    Aptible provides a PCI DSS for Service Providers Level 2 attestation, available upon request through [trust.aptible.com](https://trust.aptible.com). This attestation outlines how Aptible meets the PCI DSS Level 2 requirements, simplifying your path to compliance by inheriting many of Aptible’s pre-established controls.
  </Step>

  <Step title="Leverage Aptible for your PCI DSS Compliance">
    Aptible supports your journey toward achieving **PCI DSS compliance**. Whether you're undergoing an internal audit or working with a Qualified Security Assessor (QSA), Aptible ensures that the required security controls—such as logging, access control, vulnerability management, and encryption—are actively enforced. Additionally, the platform can help streamline the evidence collection process necessary for your audit through our [Security & Compliance Dashboard](http://localhost:3000/core-concepts/security-compliance/security-compliance-dashboard/overview) dashboard.
  </Step>

  <Step title="Show off your compliance" icon="party-horn">
    Add a `Secured by Aptible` badge and link to the Secured by Aptible page to show all the security & compliance controls implemented.

    <Frame>
      <img alt="" />
    </Frame>
  </Step>
</Steps>

# Keep Reading

<CardGroup>
  <Card title="Explore HIPAA" icon="book" href="https://www.aptible.com/docs/core-concepts/security-compliance/compliance-frameworks/hipaa">
    Learn why Aptible is the leading platform for achieving HIPAA compliance
  </Card>

  <Card title="Explore HITRUST" icon="book" href="https://www.aptible.com/docs/core-concepts/security-compliance/compliance-frameworks/hitrust">
    Learn why Aptible is the leading platform for achieving HITRUST
  </Card>
</CardGroup>


# PIPEDA
Source: https://www.aptible.com/docs/core-concepts/security-compliance/compliance-frameworks/pipeda

Learn about achieving PIPEDA compliance on Aptible

<Check>
  <Tooltip>Compliance-Ready</Tooltip>
</Check>

# Overview

Aptible’s platform is designed to help businesses meet strict data privacy and security requirements. With a strong background in serving security-focused industries, Aptible offers essential infrastructure security controls that align with PIPEDA requirements.

# Achieving PIPEDA on Aptible

<Steps>
  <Step title="Provision a Dedicated Stack to run your resources">
    Dedicated Stacks live on isolated infrastructure and are designed to support deploying resources with higher requirements like PIPEDA. As part of the shared responsibility model, Aptible automates and enforces the necessary infrastructure security and compliance controls to help customers meet PIPEDA compliance.
  </Step>

  <Step title="Review Aptible’s PIPEDA compliance resources">
    Aptible provides PIPEDA compliance resources, available upon request through [trust.aptible.com](https://trust.aptible.com). These resources outline how Aptible aligns with PIPEDA requirements, simplifying your path to compliance by inheriting many of Aptible’s pre-established controls.
  </Step>

  <Step title="Perform a PIPEDA Assessment">
    While Aptible's platform aligns with the requirements of PIPEDA, it is the **client's responsibility** to perform an assessment and ensure that the requirements are fully met based on Aptible's [devision of responsibilies](https://www.aptible.com/docs/core-concepts/architecture/reliability-division). You can conduct your **PIPEDA Self-Assessment** using the official tool provided by the Office of the Privacy Commissioner of Canada, available [here](https://www.priv.gc.ca/en/privacy-topics/privacy-laws-in-canada/the-personal-information-protection-and-electronic-documents-act-pipeda/pipeda-compliance-help/pipeda-compliance-and-training-tools/pipeda_sa_tool_200807/).
  </Step>

  <Step title="Request PIPEDA Compliance Assistance">
    Aptible supports your journey toward achieving **PIPEDA compliance**. While clients must conduct their self-assessment, Aptible ensures that critical security controls—such as access management, encryption, and secure storage—are actively enforced. Additionally, the platform can streamline the documentation collection process for your compliance program.
  </Step>

  <Step title="How to request PIPEDA Assistance from Aptible">
    To get started with PIPEDA compliance or prepare for an audit, reach out to Aptible’s support team. They’ll provide guidance on ensuring all infrastructure controls meet PIPEDA requirements and assist with necessary documentation.
  </Step>

  <Step title="Show off your compliance" icon="party-horn">
    Leverage the **Security & Compliance Dashboard** to demonstrate your PIPEDA compliance to clients and partners. Once compliant, you can display the "Secured by Aptible" badge to showcase your commitment to protecting personal information and adhering to PIPEDA standards.

    <Frame>
      <img alt="" />
    </Frame>
  </Step>
</Steps>

***

# FAQ

<AccordionGroup>
  <Accordion title="What is the relationship between PHIPA and PIPEDA?">
    The collection, use, and disclosure of personal information within the commercial sector is regulated by PIPEDA, which was enacted to manage these activities within private sector organizations. PIPEDA does not apply to personal information in provinces and territories that have “substantially similar” privacy legislation. The federal government has deemed PHIPA to be “substantially similar” to PIPEDA, exempting custodians and their agents from PIPEDA’s provisions when they collect, use, and disclose personal health information within Ontario. PIPEDA continues to apply to all commercial activities relating to the exchange of personal health information between provinces or internationally.
  </Accordion>

  <Accordion title="Does Aptible also adhere to PHIPA?">
    Aptible has been assessed towards PIPEDA compliance but not specifically towards PHIPA. While our technology stack meets the requirements common to both PIPEDA and PHIPA, it remains the client's responsibility to perform their own assessment to ensure full compliance with PHIPA when managing personal health information within Ontario.
  </Accordion>
</AccordionGroup>


# SOC 2
Source: https://www.aptible.com/docs/core-concepts/security-compliance/compliance-frameworks/soc2

Learn about achieving SOC 2 compliance on Aptible

<Check>
  <Tooltip>Compliance Fast-Track</Tooltip>
</Check>

# Overview

Aptible’s platform is engineered to help businesses meet the rigorous standards of security and compliance required by SOC 2. As a platform with a strong foundation in supporting high-security industries, Aptible automates and enforces the essential infrastructure security and compliance controls necessary for SOC 2 compliance, providing the infrastructure to fast-track your own SOC 2 attestation.

# Achieving SOC 2 on Aptible

<Steps>
  <Step title="Provision a Dedicated Stack to run your resources">
    <Info>Dedicated Stacks are available on [Production and Enterprise plans](https://www.aptible.com/pricing).</Info>
    [Dedicated Stacks](https://www.aptible.com/docs/core-concepts/architecture/stacks#stacks) operate on isolated infrastructure and are designed to support deploying resources with stringent requirements like SOC 2. Aptible provides the infrastructure necessary to implement the required security and compliance controls, which must be independently assessed by an auditor to achieve SOC 2 compliance.
  </Step>

  <Step title="Review Aptible’s SOC 2 Attestation">
    Aptible is SOC 2 attested, with documentation available upon request through [trust.aptible.com](https://trust.aptible.com). This attestation provides detailed evidence of the controls Aptible has implemented to meet SOC 2 requirements, enabling you to demonstrate to your Auditor how these controls align with your compliance needs and streamline your process.
  </Step>

  <Step title="Leverage Aptible for your SOC 2 Compliance">
    Aptible supports your journey toward achieving **SOC 2 compliance**. Whether collaborating with an external Auditor or implementing necessary controls, Aptible ensures that critical security measures—such as logging, access control, vulnerability management, and encryption—are actively managed. Additionally, our platform assists in the evidence collection process required for your audit through our [Security & Compliance Dashboard](http://localhost:3000/core-concepts/security-compliance/security-compliance-dashboard/overview).
  </Step>

  <Step title="Show off your compliance" icon="party-horn">
    Add a `Secured by Aptible` badge and link to the Secured by Aptible page to showcase all the security & compliance controls implemented.

    <Frame>
      <img alt="" />
    </Frame>
  </Step>
</Steps>

# Keep Reading

<CardGroup>
  <Card title="Explore HIPAA" icon="book" href="https://www.aptible.com/docs/core-concepts/security-compliance/compliance-frameworks/hipaa">
    Learn why Aptible is the leading platform for achieving HIPAA compliance
  </Card>

  <Card title="Explore HITRUST" icon="book" href="https://www.aptible.com/docs/core-concepts/security-compliance/compliance-frameworks/hitrust">
    Learn why Aptible is the leading platform for achieving HITRUST
  </Card>
</CardGroup>


# DDoS Protection
Source: https://www.aptible.com/docs/core-concepts/security-compliance/ddos-pid-limits

Learn how Aptible automatically provides DDoS Protection

# Overview

Aptible VPC-based approach means that most stack components are not accessible from the Internet, and cannot be targeted directly by a distributed denial-of-service (DDoS) attack. Aptible SSL/TLS endpoints include an AWS Elastic Load Balancer, which only supports valid TCP requests, meaning DDoS attacks such as UDP and SYN floods will not reach your app layer.

# PID Limits

Aptible limits the maximum number of tasks (processes or threads) running in your [containers](/docs/core-concepts/architecture/containers/overview) to protect its infrastructure against DDoS attacks, such as fork bombs.

<Note> The PID limit for a single Container is set very high (on the order of the default for a Linux system), so unless your App is misbehaving and allocating too many processes or threads, you're unlikely to ever hit this limit.</Note>

PID usage and PID limit can be monitored through [Metric Drains](/docs/core-concepts/observability/metrics/metrics-drains/overview).


# Managed Host Intrusion Detection (HIDS)
Source: https://www.aptible.com/docs/core-concepts/security-compliance/hids



# Overview

<Info> Managed Host Intrusion Detection (HIDS) is only available on [Production and Enterprise plans.](https://www.aptible.com/pricing)</Info>

Aptible is a container orchestration platform that enables users to deploy containerized workloads onto dedicated isolated networks. Each isolated network and its associated cloud infrastructure is called a [Stack](/docs/core-concepts/architecture/stacks).

Aptible stacks contain several AWS EC2 instances (virtual machines) on which Aptible users deploy their apps and databases in Docker containers. The Aptible security team is responsible for the integrity of these instances and provides a HIDS compliance report periodically as evidence of its activity.

# HIDS Compliance Report

Aptible includes access to the HIDS compliance report at no charge for all shared stacks. The report is also available for Dedicated Stacks for an additional cost. Contact Aptible Support for more information.

# Methodology

Aptible collects HIDS events using OSSEC, a leading open-source intrusion detection system. Aptible's security reporting platform ingests, and processes events generated by OSSEC in one of the following ways:

* Automated review
* Bulk review
* Manual review

If an intrusion is suspected or detected, the Aptible security team activates its incident response process to assess, contain, and eradicate the threat and notifies affected users, if any.

# Review Process

The Aptible Security team uses the following review processes for intrusion detection.

## Automated Review

Aptible's security reporting platform automatically reviews a certain number of events generated by OSSEC.

Here are some examples of automated reviews:

* Purely informational events, such as events indicating that OSSEC performed a periodic integrity check. Their sole purpose is to let them appear in the HIDS compliance report.
* Acceptable security events. For example, an automated script running as root using `sudo`: using `sudo` is technically a relevant security event, but if the user already has root privileges, it cannot result in privilege escalation, so that event is automatically approved.

## Bulk Review

Aptible's security reporting platform integrates with several other systems with which members of the Aptible Operations and Security teams interact. Aptible's security reporting platform collects information from these different systems to determine whether the events generated by OSSEC can be approved without further review.

Here are some notable examples of bulk-reviewed events:

* When a successful SSH login occurs on an Aptible instance, Aptible's monitoring determines whether the SSH login can be tied to an authorized Aptible Operations team member and, if so, prompts them via Slack to confirm that they did trigger this login. An alert is immediately escalated to the Aptible security team if no authorized team member is found or the team member takes too long to respond. Related IDS events will automatically be approved and flagged as bulk review when a login is approved.
* When a member of the Aptible Operations team deploys updated software via AWS OpsWorks to Aptible hosts, corresponding file integrity alerts are automatically approved in Aptible's security reporting platform and flagged as bulk reviews.

## Manual Review

The Aptible Security team manually reviews any security event that is neither reviewed automatically nor in bulk.

Some examples of manually-reviewed events include:

* Malware detection events. Malware detection is often racy and generates several false positives, which need to be manually reviewed by Aptible.
* Configuration changes that were not otherwise bulk-reviewed. For example, changes that result from nightly automated security updates.

# List of Security Events

Security Events monitored by Aptible Host Intrusion Detection:

## CIS benchmark non-conformance

HIDS generates this event when Aptible's monitoring detects an instance that does not conform to the CIS controls Aptible is currently targeting. These events are often triggered on older instances that still need configuring to follow Aptible's latest security best practices.

Aptible's Security team remediates the underlying non-conformance by replacing or reconfiguring the instance, and the team uses the severity of the non-conformance to determine priority.

## File integrity change

HIDS generates this event when Aptible's monitoring detects changes to a monitored file. These events are often the result of package updates, deployments, or the activity of Aptible operations team members and are reviewed accordingly.

## Other informational event

HIDS generates this event when Aptible's monitoring detects an otherwise un-categorized informational event. These events are often auto-reviewed due to their informational nature, and the Aptible security team uses them for high-level reporting.

## Periodic rootkit check

Aptible performs a periodic scan for resident rootkits and other malware. HIDS generates this event every time the scan is performed. HIDS generates a rootkit check event alert if any potential infection is detected.

## Periodic system integrity check

Aptible performs a periodic system integrity check to scan for new files in monitored system directories and deleted files. HIDS generates this event every time the scan is performed.

Among others, this scan covers `/etc`, `/bin`, `/sbin`, `/boot`, `/usr/bin`, `/usr/sbin`.

Note that Aptible also monitors changes to files under these directories in real-time. If they change, HIDS generates a file integrity alert.

## Privilege escalation (e.g., sudo, su)

HIDS generates this event when Aptible's monitoring detects a user escalated their privileges on a host using tools such as sudo or su. This activity is often the result of automated maintenance scripts or the action of Aptible Operations team members and is reviewed accordingly.

## Rootkit check event

HIDS generates this event when Aptible's monitoring detects potential rootkit or malware infection. Due to the inherently racy nature of most rootkit scanning techniques, these events are often false positives, but they are all investigated by Aptible's security team.

## SSH login

HIDS generates this event when Aptible's monitoring detects host-level access via SSH. Whenever they log in to a host, Aptible operations team members are prompted to confirm that the activity is legitimate, so these events are often reviewed in bulk.

## Uncategorized event

HIDS generates this event for uncategorized events generated by Aptible's monitoring. These events are often reviewed directly by the Aptible security team.

## User or group modification

HIDS generates this event when Aptible's monitoring detects that a user or group was changed on the system. This change is usually the result of the activity of Aptible Operations team members.


# Security & Compliance - Overview
Source: https://www.aptible.com/docs/core-concepts/security-compliance/overview

Learn how Aptible enables dev teams to meet regulatory compliance requirements (HIPAA, HITRUST, SOC 2, PCI) and pass security audits

# Overview

[Our story](/docs/getting-started/introduction#our-story) began with a strong focus on security and compliance, making us the leading Platform as a Service (PaaS) for security and compliance.

We provide developer-friendly infrastructure guardrails and solutions to help our customers navigate security audits and achieve compliance. This includes:

* **Security best practices, out-of-the-box**: When you provision a [dedicated stack](/docs/core-concepts/architecture/stacks), you automatically unlock a [suite of security features](https://www.aptible.com/secured-by-aptible), including encryption, [DDoS protection](/docs/core-concepts/security-compliance/ddos-pid-limits), host hardening, and [intrusion detection](/docs/core-concepts/security-compliance/hids), alleviating the need to worry about security best practices.
* **Security and Compliance Dashboard**: The [Security & Compliance Dashboard](/docs/core-concepts/security-compliance/security-compliance-dashboard/overview) provides a unified view of the implemented security controls —  track progress, achieve compliance, and easily generate summarized reports.
* **Access control**: Secure access to your resources is ensured with [granular user permission](/docs/core-concepts/security-compliance/access-permissions) controls, [Multi-Factor Authentication (MFA)](/docs/core-concepts/security-compliance/authentication/password-authentication#2-factor-authentication-2fa), and [Single Sign-On (SSO)](/docs/core-concepts/security-compliance/authentication/sso) support.
* **Compliance made easy**: We provide HIPAA Business Associate Agreements (BAAs), HITRUST Inheritance, and streamlined SOC 2 compliance solutions — CISO-approved.

# Learn more about security functionality

<CardGroup>
  <Card title=" Authentication" icon="book" href="https://www.aptible.com/docs/authenticating-with-aptible">
    Learn about password authentication, SCIM, SSH keys, and Single Sign-On (SSO)
  </Card>

  <Card title="Roles & Permissions" icon="book" href="https://www.aptible.com/docs/access-permissions">
    Learn to managr roles & permissions
  </Card>

  <Card title="Security & Compliance Dashboard" icon="book" href="https://www.aptible.com/docs/intro-compliance-dashboard">
    Learn to review, manage, and showcase your security & compliance controls
  </Card>

  <Card title="DDoS Protection" icon="book" href="https://www.aptible.com/docs/pid-limits">
    Learn about Aptible's DDoS Protection
  </Card>

  <Card title="Managed Host Intrusion Detection (HIDS)" icon="book" href="https://www.aptible.com/docs/hids">
    Learn about Aptible's methodoloy and process for intrusion detection
  </Card>

  <Card title="Image and Vulnerability Scanning" icon="book" href="/how-to-guides/platform-guides/image-vulnerability-scanning">
    Lint Dockerfiles and scan images in CI/CD before deploy, and keep scanning between releases
  </Card>
</CardGroup>

# FAQ

<AccordionGroup>
  <Accordion title="How do I achieve HIPAA compliance with Aptible?">
    ## Read the guide

    <Card title="How to achieve HIPAA compliance" icon="book-open-reader" href="https://www.aptible.com/docs/achieve-hipaa" />
  </Accordion>

  <Accordion title="How do I achieve HITRUST compliance with Aptible?">
    ## Read the guide

    <Card title="How to navigate HITRUST Certification" icon="book-open-reader" href="https://www.aptible.com/docs/requesting-hitrust-inheritance" />
  </Accordion>

  <Accordion title="How should I navigate security questionnaires and audits?">
    ## Read the guide

    <Card title="How to navigate security questionnaires and audits" icon="book-open-reader" href="https://www.aptible.com/docs/security-questionnaires" />
  </Accordion>

  <Accordion title="Does Aptible provide anti-virus/anti-malware/anti-spyware software?">
    Aptible does not currently run antivirus on our platform; this is because the Aptible infrastructure does not run email clients or web browsers, which are by far the most common vector for virus infection. We do however run Host Intrusion Detection Software (HIDS 12) which scans for malware on container hosts. Additionally, our security program does mandate that we run antivirus on Aptible employee workstations and laptops.
  </Accordion>

  <Accordion title="How do I access SOC 2 reports and other security documentation?">
    Aptible maintains compliance with programs and frameworks including SOC 2 Type II, GDPR, HIPAA, PCI, HITRUST, EU-US Data Privacy Framework, PIPEDA, Swiss-US Data Privacy Framework, and the UK Extension to the EU-US Data Privacy Framework.

    We provide documents attesting to our ongoing compliance for use as evidence in your organization's compliance process. Access is provided through [trust.aptible.com](https://trust.aptible.com/). Use **Request or Regain Access** with the email address associated with your Aptible account.

    Aptible requires the intended consumer of confidential reports to have an NDA in place directly with Aptible. Through the trust portal, you can e-sign the mutual NDA and access documents such as:

    * HITRUST Engagement Letter
    * HITRUST CSF Letter of Certification
    * HITRUST NIST CSF Assessment
    * HITRUST CSF Validated Assessment Report
    * SOC 2 Type 2 Report
    * SOC 2 Continued Operations Letter
    * Penetration Test Summary

    If you have trouble accessing the portal or need special assistance, contact [Aptible Support](/docs/how-to-guides/troubleshooting/aptible-support).
  </Accordion>
</AccordionGroup>


# Compliance Readiness Scores
Source: https://www.aptible.com/docs/core-concepts/security-compliance/security-compliance-dashboard/compliance-readiness-scores



The performance of the security controls in the Security & Compliance Dashboard affects your readiness score towards regulations and frameworks like HIPAA and HITRUST. These scores tell you how effectively you have implemented infrastructure controls to meet these frameworks’ requirements.

<img alt="Image" />

Aptible has mapped the controls visualized in the Dashboard to HIPAA and HITRUST requirements.

# HIPAA Readiness Score

The Health Insurance Portability and Accountability Act of 1996 (HIPAA) is a federal law that dictates US standards to protect sensitive patient health information from being disclosed without the patient’s consent or knowledge. The [US Department of Health and Human Services (HHS)](https://www.hhs.gov/hipaa/index.html) issued the HIPAA Privacy Rule to implement the requirements of HIPAA. The HIPAA Security Rule protects a subset of information covered by the Privacy Rule.

The Aptible Security & Compliance Dashboard provides a HIPAA readiness score based on controls required for meeting the minimum standards of the regulation, labeled HIPAA Required, as well as addressable controls that are not required to meet the specifications of the regulation but are recommended as a good security practice, labeled HIPAA Addressable.

## HIPAA Required Score

HIPAA prescribes certain implementation specifications as “required, “meaning you must implement the control to meet the regulation requirements. An example of such a specification is 164.308(a)(7)(ii)(A), requiring implemented procedures to create and maintain retrievable exact copies of ePHI. You can meet this specification with Aptible’s [automated daily backup creation and retention policy](/docs/core-concepts/managed-databases/managing-databases/database-backups).

The HIPAA Required score gives you a binary indicator of whether or not you’re meeting the required specifications under the regulation. By default, all resources hosted on a [Dedicated Stack](/docs/core-concepts/architecture/stacks) meet the required specifications of HIPAA, so if you plan on processing ePHI, it’s a good idea to host your containers on a Dedicated Stack from day 1.

## HIPAA Addressable Score

The HHS developed the concept of “addressable implementation specifications” to provide covered entities and business associates additional flexibility regarding compliance with HIPAA. In meeting standards that contain addressable implementation specifications, a covered entity or business associate will do one of the following for each addressable specification:

* Implement the addressable implementation specifications;
* Implement one or more alternative security measures to accomplish the same purpose;
* Not implement either an addressable implementation specification or an alternative.

The HIPAA Addressable score tells you what percentage of infrastructure controls you have implemented successfully to meet relevant addressable specifications per HIPAA guidelines.

# HITRUST-CSF Readiness Score

The [HITRUST Common Security Framework (CSF) Certification](https://hitrustalliance.net/product-tool/hitrust-csf/) is a compliance framework based on ISO/IEC 27001. It integrates HIPAA, HITECH, and a variety of other state, local, and industry frameworks and best practices. Independent assessors award this certification when they find that an organization has achieved certain maturity levels in implementing the required HITRUST CSF controls.

HITRUST CSF is unique because it allows customers to inherit security controls from the infrastructure they host their resources on if the infrastructure provider is also HITRUST CSF certified, enabling you to save time and resources when you begin your certification process. Aptible is HITRUST certified, meaning you can fully inherit up to 30% of security controls implemented and managed by Aptible and partially inherit up to 50% of security controls.

The Aptible Security & Compliance Dashboard provides a HITRUST readiness score based on controls required for meeting the standards of HITRUST CSF regulation. The HITRUST score tells you what percentage of infrastructure controls you have successfully implemented to meet relevant HITRUST guidelines.


# Control Performance
Source: https://www.aptible.com/docs/core-concepts/security-compliance/security-compliance-dashboard/control-performance



Security controls in-place check for the implementation of a specific safeguard. If you have not implemented a particular control , appropriate notifications are provided in the Aprible Dashboard to indicate the same, with relevant recommendations to remediate.

You can choose to ignore a control implementation, thereby no longer seeing the notification in the Aptible Dashboard and ensuring it does not affect your overall compliance readiness score.

In the example below, [container logging](/docs/core-concepts/observability/logs/overview) was not implemented in the *aptible-misc* environment.

<img alt="Image" />

In such a scenario, you have two options:

## Option 1: Remediate and Implement Control

Based on the remediation recommendations provided in the platform for a control you haven’t implemented, you could follow the appropriate instructions to implement the control in question. Coming to the example provided above, the user with `write` access to the aptible-misc environment can configure a log drain collecting and aggregating their container logs in a destination of choice. Doing this would be an acceptable implementation of the specific control, thereby remediating the issue of non-compliance.

## Option 2: Ignore Implementation

You could also ignore the control implementation based on your organization’s judgment for the specific resource. Choosing to ignore the control implementation will signal to Aptible to also ignore the implementation of the particular control, which in the example above, was the *aptible-misc* environment. Doing so would no longer show you a warning in the UI indicating that you have not implemented the control  and would ensure it does not affect your compliance readiness score.

You can see control implementations you’ve ignored in the expanded view of each control. You can also unignore the control implementation if needed.

<img alt="Image" />


# Security & Compliance Dashboard
Source: https://www.aptible.com/docs/core-concepts/security-compliance/security-compliance-dashboard/overview



<img alt="" />

The Aptible Security & Compliance Dashboard provides a unified, easy-to-consume view of all the security controls Aptible fully enforces and manages on your behalf, as well as the configurations you manage on Aptible that can affect the security of your apps, databases, and endpoints hosted on the platform.

Security controls are safeguards implemented to protect various forms of data and infrastructure that are important for compliance satisfaction and general best-practice security.

You can use the Security & Compliance Dashboard to review the implementation details and the performance of the various security controls implemented on Aptible. Based on the performance of these controls, the Dashboard also provides you with actionable recommendations around control implementations you can configure for your hosted resources on the platform to improve your overall security posture and accelerate compliance with relevant frameworks like HIPAA and HITRUST.

Apart from being visualized in this Aptible Dashboard, you can export these controls as a print-friendly PDF to share externally with prospects and auditors to gain their trust and confidence faster. Access the Dashboard by logging into your [Aptible account](https://account.aptible.com/) and clicking the *Security and Compliance* tab in the navigation bar. You'll need to have [Full Visibility (Read)](https://www.aptible.com/docs/core-concepts/security-compliance/access-permissions#read-permissions) permissions to one or more environments to access the Security and Compliance Dashboard.

Each control comes with a description to give your teams an overview of what the safeguard entails and an auditor-friendly description to share externally during compliance audits. You can find these descriptions by clicking on any control from the list in the Security & Compliance Dashboard.


# Resources in Scope
Source: https://www.aptible.com/docs/core-concepts/security-compliance/security-compliance-dashboard/resources-in-scope



Aptible considers any containerized apps, databases, and their associated endpoints across different Aptible environments hosted on your Shared and Dedicated Stacks and users with access to these workloads. Aptible tests each resource for various security controls Aptible has identified as per our [division of responsibilities](https://www.aptible.com/secured-by-aptible).

Aptible splits security controls across different categories that pertain to various pieces of an organization’s overall security posture. These categories include:

* Access Management
* Auditing
* Business Continuity
* Encryption
* Network Protection
* Platform Security
* Vulnerability Management

Every control tests for security safeguard implementation for specific resources in scope. For example, the *Multi-factor Authentication* control tests for the activation and enforcement of [MFA/2FA](/docs/core-concepts/security-compliance/authentication/password-authentication#2-factor-authentication-2fa) on the account level, whereas a control like *Cross-region backups* is applied on the database level, testing whether or not you’ve enabled the auto-creation of [geographically redundant copy of each database backup](/docs/core-concepts/managed-databases/managing-databases/database-backups) for disaster recovery purposes.

You can see resources in scope by clicking on a control of interest.

<img alt="Image" />


# Shareable Compliance Posture Report
Source: https://www.aptible.com/docs/core-concepts/security-compliance/security-compliance-dashboard/shareable-compliance-report



You can generate a shareable PDF of your overall security and compliance posture based on the controls implemented. This shareable report lets you quickly provide various internal stakeholders, external auditors, and customers with an in-depth understanding of your infrastructure security and compliance posture, thereby building trust in your organization’s security.

You can do this by clicking the *View as Printable Summary Report* button in the Security & Compliance Dashboard.

<img alt="Image" />

Clicking this will open up a print-friendly view that details the implementation of the various controls against the resources in scope for each of them. You can then save this report as a PDF and download it to your local drive by following the instructions from the prompt.

<img alt="Image" />

The print-friendly report will honor the environment and control filters from the Compliance Visibility Dashboard. For example, if you’ve filtered to specific environments and control categories, the resulting print-friendly report would only highlight the control implementations pertaining to the filtered environments and categories.


# Create your first LLM key
Source: https://www.aptible.com/docs/getting-started/create-your-first-llm-key

Learn how to create an LLM key and start using Aptible's AI Gateway

## Overview

The following guide is designed to help you create your first LLM key on Aptible. The [Aptible AI Gateway](/docs/ai-gateway) is a single API to access Anthropic, OpenAI, and Amazon Bedrock, with security and compliance guardrails built in (e.g., encryption, audit logging), and an easy-to-use interface to manage keys, control model access, and use LLMs securely. LLM keys are how you authenticate requests to the AI Gateway, a managed proxy that gives you secure, auditable access to leading AI model providers without needing to manage provider credentials directly in your apps.

For a full overview of the AI Gateway, see the [AI Gateway documentation](/docs/core-concepts/ai-gateway).

## Create an LLM Key

<Tabs>
  <Tab title="New Customers">
    <Steps>
      <Step title="Start your trial to try for free">
        [Sign up](https://app.aptible.com/signup) for or [sign in](https://app.aptible.com/login) to your Aptible account. Then navigate to the [AI Gateway Dashboard](https://app.aptible.com/llm-keys) to activate your trial.

        <Frame>
          <img alt="AI Gateway Dashboard" />

          *AI Gateway trial enrollment*
        </Frame>

        From there you'll be redirected to the LLM Keys dashboard. You'll receive \$10 of LLM credits to get you started, which can be used with any models that we support. If you want to upgrade to a paid plan for more credits, [contact Aptible Support.](https://app.aptible.com/support?subject=Upgrade+to+paid+AI+Gateway+plan\&message=To+upgrade+to+a+paid+AI+Gateway+plan%2C+submit+this+form+and+the+Aptible+Support+team+will+be+in+touch+soon.%0A%0A)

        <Frame>
          <img alt="Screenshot 2026 06 03 At 12 23 46 PM" />
        </Frame>

        <Warning>
          **For those processing PHI:** You will need to execute a BAA before you can start processing PHI using the AI Gateway. Contact Aptible Support to execute one.
        </Warning>
      </Step>

      <Step title="Create an LLM key">
        Click **Create LLM Key** on the AI Gateway Dashboard.

        You'll start by creating an Environment, which is how keys and resources are organized in Aptible. This will help you apply model access controls and other permissions to your keys.

        <Frame>
          <img alt="Screenshot 2026 06 03 At 2 57 33 PM" />
        </Frame>

        Then, create your key.

        <Frame>
          <img alt="Screenshot 2026 06 03 At 3 02 30 PM" />
        </Frame>

        <Tip>
          Give it a descriptive name so you can identify its usage later when reviewing costs and request history.
        </Tip>

        Once that is complete, you will receive your LLM Key and the Endpoint URL. Make sure to copy the key, as you won't be able to see it again after you close this window.

        <Frame>
          <img alt="Screenshot 2026 06 03 At 3 10 32 PM" />
        </Frame>
      </Step>

      <Step title="Connect to the gateway">
        You will use this single endpoint to connect to the gateway for all models:

        ```text theme={null}
                https://llm-gateway-api.aptible.com
        ```

        Specific configuration requirements will vary by AI tool. Here are instructions for setting up Claude Desktop to use your key:

        * Enable Developer Mode: Open Claude Desktop and go to Help > Troubleshooting > Enable Developer Mode.
        * Access Inference Settings: A new "Developer" menu will appear after Claude restarts. Click Developer > Configure third-party inference.
        * Enter the Gateway base URL: Select "Gateway" as your connection type, and use [https://llm-gateway-api.aptible.com](https://llm-gateway-api.aptible.com).
        * Set your Gateway API key: paste your Aptible LLM key here, and set the Gateway auth scheme to "bearer".
        * Save and Restart: Click Apply locally, then fully quit and restart Claude Desktop to load the new settings. You can also use LLM keys with any OpenAI-compatible client:

        <CodeGroup>
          ```python via any OpenAI-compatible client theme={null}
                  import openai

                  client = openai.OpenAI(
                      api_key="YOUR_AI_GATEWAY_KEY",
                      base_url="https://llm-gateway-api.aptible.com",
                  )

                  response = client.chat.completions.create(
                      model="anthropic/claude-sonnet-4-20250514",
                      messages=[
                          {"role": "user", "content": "Hello world!"}
                      ],
                  )

                  print(response)
          ```
        </CodeGroup>
      </Step>

      <Step title="Start using your LLM Keys!">
        Once that is complete, you're ready to start using your LLM Keys securely! All your LLM usage will be encrypted and logged for auditability.

        When you're ready to upgrade to a paid AI Gateway plan, [contact Aptible Support](https://app.aptible.com/support?subject=Upgrade+to+paid+AI+Gateway+plan\&message=To+upgrade+to+a+paid+AI+Gateway+plan%2C+submit+this+form+and+the+Aptible+Support+team+will+be+in+touch+soon.%0A%0A) here or via the Aptible Dashboard. Note: this will require having a [payment method](https://app.aptible.com/settings/billing/payment-methods) on file.
      </Step>

      <Step title=" Optionally, start using with PHI">
        To begin using the AI Gateway with PHI, you'll need to upgrade to a paid plan and execute a BAA with Aptible. [Contact Aptible Support](https://app.aptible.com/support?subject=Upgrade+to+paid+AI+Gateway+plan\&message=To+upgrade+to+a+paid+AI+Gateway+plan%2C+submit+this+form+and+the+Aptible+Support+team+will+be+in+touch+soon.%0A%0A) here or via the Aptible Dashboard to continue.

        Once you have completed these steps, you're ready to start processing PHI! Aptible will ensure your usage is encrypted, logged, and never stored for model training.
      </Step>

      <Step title="Optionally, configure model access">
        You can see the available models in the key details page; copy your desired model string and use it wherever you use your LLM key. This view shows which models your key has access to.

        <Frame>
          <img alt="Screenshot 2026 06 03 At 4 09 26 PM" />
        </Frame>

        Model access is configured at the environment level — all keys within a given environment share the same model access policy. To change which models are available, update the model access settings on the environment.
      </Step>

      <Step title="Review costs and optionally, configure limits">
        View per-key costs for the current billing period, request history for the past week, and token consumption per request.

        <Frame>
          <img alt="Llm Key Details" />
        </Frame>
      </Step>
    </Steps>
  </Tab>
</Tabs>


# Deploy your custom code
Source: https://www.aptible.com/docs/getting-started/deploy-custom-code

Ship your own code using Git or Docker.

## Overview

The following guide is designed to help you deploy custom code on Aptible. During this process, Aptible will launch containers to run your custom app and Managed Databases for any data stores, like PostgreSQL, Redis, etc., that your app requires to run.

## Compatibility

Aptible supports many frameworks; you can deploy any code that meets the following requirements:

* **Apps must run on Linux in Docker containers**
* **Apps may only receive traffic over HTTP or TCP.**
  * App endpoints (load balancers) are how you expose your Aptible app to the Internet. These endpoints only support traffic received over HTTP or TCP. While you cannot serve UDP services from Aptible, you may still connect to UDP services (such as DNS, SNMP, etc.) from apps hosted on Aptible.
* **Apps should not depend on persistent storage by default.**
  * App containers on Aptible run with an ephemeral filesystem and cannot be used for data persistence on their own. To store your data with persistence, we recommend using a [Database](http://aptible.com/docs/databases) or third-party storage solution, such as AWS S3. For workloads that need a small amount of durable local state, you can attach a [Persistent Disk](/docs/core-concepts/apps/persistent-disks) to a single-container App service. Apps that rely on a volume shared between multiple containers must still be re-architected to run on Aptible. If you have questions about doing so, contact [Aptible Support](/docs/how-to-guides/troubleshooting/aptible-support) for assistance.

# Deploy Code

<Info>
  Prerequisites: Ensure you have [Git](https://git-scm.com/downloads) installed, a Git repository with your application code, and a [Dockerfile](/docs/core-concepts/apps/deploying-apps/image/deploying-with-git/overview) ready to deploy.
</Info>

Using the Deploy Code tool in the Aptible Dashboard, you can deploy Custom Code. The tool will guide you through the following:

<Steps>
  <Step title="Deploy with Git Push">
    <img alt="" />
  </Step>

  <Step title="Add an SSH key">
    <img /> If you have not done so already, you will be prompted to set up an [SSH key](/docs/core-concepts/security-compliance/authentication/ssh-keys#ssh-keys).
  </Step>

  <Step title="Environment Setup">
    <img /> Select your [stack](/docs/core-concepts/architecture/stacks) to deploy your resources. This will determine what region your resources are deployed to. Then, name the [environment](/docs/core-concepts/architecture/environments) your resources will be grouped into.
  </Step>

  <Step title="Push your code to Aptible">
    <img /> Select **Custom Code** deployment, and from your command-line interface, add Aptible’s Git Server and push your code to our scan branch using the commands in the Aptible Dashboard
  </Step>

  <Step title="Provision a database and configure your app">
    <img /> Optionally, provision a database, configure your app with [environment variables](/docs/core-concepts/apps/deploying-apps/configuration#configuration-variables), or add additional [services](/docs/core-concepts/apps/deploying-apps/services) and commands.
  </Step>

  <Step title="Deploy your code and view logs">
    <img /> Deploy your code and view [logs](/docs/core-concepts/observability/logs/overview) in real time
  </Step>

  <Step title="Expose your app to the internet">
    <img /> Now that your code is deployed, it's time to expose your app to the internet. Select the service that needs an [endpoint](/docs/core-concepts/apps/connecting-to-apps/app-endpoints/overview), and Aptible will automatically provision a managed endpoint.
  </Step>

  <Step title="View your deployed app 🎉" icon="party-horn" />
</Steps>


# Deploy a Node.js + Express Template
Source: https://www.aptible.com/docs/getting-started/deploy-starter-template/node-js

Deploy a starter template Node.js app using the Express framework on Aptible

<CardGroup>
  <Card title="Deploy Now" icon="rocket" href="https://app.aptible.com/create" />

  <Card title="GitHub Repo" icon="github" href="https://github.com/aptible/template-express" />

  <Card title="View Example" icon="browser" href="https://app-52737.on-aptible.com/" />
</CardGroup>

# Overview

The following guide is designed to help you deploy a sample [Node.js](https://nodejs.org/) app using the [Express framework](https://expressjs.com/) from the Aptible Dashboard.

# Deploying the template

<Info>
  Prerequisite: Ensure you have [Git](https://git-scm.com/downloads) installed.
</Info>

Using the [Deploy Code](https://app.aptible.com/create) tool in the Aptible Dashboard, you can deploy the **Express Template**. The tool will guide you through the following:

<Steps>
  <Step title="Deploy with Git Push">
    <img alt="" />
  </Step>

  <Step title="Add an SSH key">
    <img /> If you have not done so already, you will be prompted to set up an [SSH key](/docs/core-concepts/security-compliance/authentication/ssh-keys#ssh-keys).
  </Step>

  <Step title="Environment Setup">
    <img />\
    Select your [Stack](/docs/core-concepts/architecture/stacks) to deploy your resources. This will determine what region your resources are deployed to. Then, name the [Environment](/docs/core-concepts/architecture/environments) your resources will be grouped into.
  </Step>

  <Step title="Prepare the template">
    <img /> Select **Express Template** for deployment, and follow command-line instructions.
  </Step>

  <Step title="Fill environment variables and deploy">
    <img alt="" />

    Aptible will automatically fill this template's required databases, services, and app's configuration with environment variable keys for you to fill with values. Once complete, save and deploy the code!

    Aptible will stream logs to you in live time: <img />
  </Step>

  <Step title="Expose your app to the internet">
    <img /> Now that your code is deployed, it's time to expose your app to the internet. Select the service that needs an [endpoint](/docs/core-concepts/apps/connecting-to-apps/app-endpoints/overview), and Aptible will automatically provision a managed endpoint.
  </Step>

  <Step title="View your deployed app" icon="party-horn">
    <img alt="" />
  </Step>
</Steps>

# Continue your journey

<Card title="Deploy custom code" icon="books" href="https://www.aptible.com/docs/custom-code-quickstart">
  Read our guide for deploying custom code on Aptible.
</Card>


# Deploy a PHP + Laravel Template
Source: https://www.aptible.com/docs/getting-started/deploy-starter-template/php-laravel

Deploy a starter template PHP app using the Laravel framework on Aptible

<CardGroup>
  <Card title="Deploy Now" icon="rocket" href="https://app.aptible.com/create" />

  <Card title="GitHub Repo" icon="github" href="https://github.com/aptible/template-laravel" />

  <Card title="View Live Example" icon="browser" href="https://app-52756.on-aptible.com/" />
</CardGroup>

# Overview

This guide will walk you through the process of launching a PHP app using the [Laravel framework](https://laravel.com/).

# Deploy Template

<Info>
  Prerequisite: Ensure you have [Git](https://git-scm.com/downloads) installed.
</Info>

Using the [Deploy Code](https://app.aptible.com/create) tool in the Aptible Dashboard, you can deploy the **Laravel Template**. The tool will guide you through the following:

<Steps>
  <Step title="Deploy with Git Push">
    <img alt="" />
  </Step>

  <Step title="Add an SSH key">
    <img /> If you have not done so already, you will be prompted to set up an [SSH key](/docs/core-concepts/security-compliance/authentication/ssh-keys#ssh-keys).
  </Step>

  <Step title="Environment Setup">
    <img /> Select your [stack](/docs/core-concepts/architecture/stacks) to deploy your resources. This will determine what region your resources are deployed to. Then, name the [environment](/docs/core-concepts/architecture/environments) your resources will be grouped into.
  </Step>

  <Step title="Prepare the template">
    <img /> Select **Laravel Template** for deployment, and follow command-line instructions.
  </Step>

  <Step title="Fill environment variables and deploy!">
    <img /> Aptible will automatically fill this template's required databases, services, and app's configuration with environment variable keys for you to fill with values. Once complete, save and deploy the code!

    Aptible will stream the logs to you in live time: <img />
  </Step>

  <Step title="Expose your app to the internet">
    <img /> Now that your code is deployed, it's time to expose your app to the internet. Select the service that needs an [endpoint](/docs/core-concepts/apps/connecting-to-apps/app-endpoints/overview), and Aptible will automatically provision a managed endpoint.
  </Step>

  <Step title="View your deployed app" icon="party-horn">
    <img alt="" />
  </Step>
</Steps>

# Continue your journey

<Card title="Deploy custom code" icon="books" href="https://www.aptible.com/docs/custom-code-quickstart">
  Read our guide for deploying custom code on Aptible.
</Card>


# Deploy a Python + Django Template
Source: https://www.aptible.com/docs/getting-started/deploy-starter-template/python-django

Deploy a starter template Python app using the Django framework on Aptible

<CardGroup>
  <Card title="Deploy Now" icon="rocket" href="https://app.aptible.com/create" />

  <Card title="GitHub Repo" icon="github" href="https://github.com/aptible/template-django" />

  <Card title="View Example" icon="browser" href="https://app-52709.on-aptible.com/" />
</CardGroup>

# Overview

This guide will walk you through the process of launching a [Python](https://www.python.org/) app using the [Django](https://www.djangoproject.com/) framework.

# Deploy Template

<Info>
  Prerequisite: Ensure you have [Git](https://git-scm.com/downloads) installed.
</Info>

Using the [Deploy Code](https://app.aptible.com/create) tool in the Aptible Dashboard, you can deploy the **Django Template**. The tool will guide you through the following:

<Steps>
  <Step title="Deploy with Git Push">
    <img alt="" />
  </Step>

  <Step title="Add an SSH key">
    <img /> If you have not done so already, you will be prompted to set up an [SSH key](/docs/core-concepts/security-compliance/authentication/ssh-keys#ssh-keys).
  </Step>

  <Step title="Environment Setup">
    <img /> Select your [stack](/docs/core-concepts/architecture/stacks) to deploy your resources. This will determine what region your resources are deployed to. Then, the name the [environment](/docs/core-concepts/architecture/environments) your resources will be grouped into.
  </Step>

  <Step title="Prepare the template">
    <img /> Select **Django Template** for deployment, and follow command-line instructions.
  </Step>

  <Step title="Fill environment variables and deploy!">
    <img /> Aptible will automatically fill this template's required databases, services, and app's configuration with environment variable keys for you to fill with values. Once complete, save and deploy the code!

    Aptible will stream the logs to you in live time: <img />
  </Step>

  <Step title="Expose your app to the internet">
    <img /> Now that your code is deployed, it's time to expose your app to the internet. Select the service that needs an [endpoint](/docs/core-concepts/apps/connecting-to-apps/app-endpoints/overview), and Aptible will automatically provision a managed endpoint.
  </Step>

  <Step title="View your deployed app" icon="party-horn">
    <img alt="" />
  </Step>
</Steps>

# Continue your journey

<Card title="Deploy custom code" icon="books" href="https://www.aptible.com/docs/custom-code-quickstart">
  Read our guide for deploying custom code on Aptible.
</Card>


# Deploy a Python + Flask Demo App
Source: https://www.aptible.com/docs/getting-started/deploy-starter-template/python-flask

Deploy our Python demo app using the Flask framework with Managed PostgreSQL Database and Redis instance

<CardGroup>
  <Card title="Deploy Now" icon="rocket" href="https://app.aptible.com/create" />

  <Card title="GitHub Repo" icon="github" href="https://github.com/aptible/deploy-demo-app" />

  <Card title="View Example" icon="browser" href="https://app-60388.on-aptible.com/" />
</CardGroup>

# Overview

The following guide is designed to help you deploy an example app on Aptible. During this process, Aptible will launch containers to run a Python app with a web server, a background worker, a Managed PostgreSQL Database, and a Redis instance.

<Frame>
  <img alt="" />
</Frame>

The demo app displays the last 20 messages of the database, including any additional messages you record via the "message board." The application was designed to guide new users through a "Setup Checklist" which showcases various features of the Aptible platform (such as database migration, scaling, etc.) using both the dashboard and Aptible CLI.

# Deploy App

<Info>
  Prerequisite: Ensure you have [Git](https://git-scm.com/downloads) installed.
</Info>

Using the [Deploy Code](https://app.aptible.com/create) tool in the Aptible Dashboard, you can deploy the **Deploy Demo App**. The tool will guide you through the following:

<Steps>
  <Step title="Deploy with Git Push">
    <img alt="" />
  </Step>

  <Step title="Add an SSH key">
    <img /> If you have not done so already, you will be prompted to set up an [SSH key](/docs/core-concepts/security-compliance/authentication/ssh-keys#ssh-keys).
  </Step>

  <Step title="Environment Setup">
    <img /> Select your [stack](/docs/core-concepts/architecture/stacks) to deploy your resources. This will determine what region your resources are deployed to. Then, name the [environment](/docs/core-concepts/architecture/environments) your resources will be grouped into.
  </Step>

  <Step title="Prepare the template">
    <img /> Select **Deploy Demo App** for deployment, and follow command-line instructions.
  </Step>

  <Step title="Fill environment variables and deploy">
    <img /> Aptible will automatically fill this template's app configuration, services, and required databases. This includes: a web server, a background worker, a Managed PostgreSQL Database, and a Redis instance. All you have to do is fill the complete the environment variables save and deploy the code!

    Aptible will show you the logs in live time: <img />
  </Step>

  <Step title="Expose your app to the internet">
    <img /> Now that your code is deployed, it's time to expose your app to the internet. Select the service that needs an [endpoint](/docs/core-concepts/apps/connecting-to-apps/app-endpoints/overview), and Aptible will automatically provision a managed endpoint.
  </Step>

  <Step title="View your deployed app" icon="party-horn">
    <Frame>
      <img alt="" />
    </Frame>

    From here, you can optionally test the application's message board and/or "Setup Checklist."
  </Step>
</Steps>

# Continue your journey

<Card title="Deploy custom code" icon="books" href="https://www.aptible.com/docs/custom-code-quickstart">
  Read our guide for deploying custom code on Aptible.
</Card>


# Deploy a Ruby on Rails Template
Source: https://www.aptible.com/docs/getting-started/deploy-starter-template/ruby-on-rails

Deploy a starter template Ruby on Rails app on Aptible

<CardGroup>
  <Card title="Deploy Now" icon="rocket" href="https://app.aptible.com/create" />

  <Card title="GitHub Repo" icon="github" href="https://github.com/aptible/template-rails" />

  <Card title="View Example" icon="browser" href="https://app-52710.on-aptible.com/" />
</CardGroup>

# Overview

This guide will walk you through the process of launching the [Rails Getting Started example](https://guides.rubyonrails.org/v4.2.7/getting_started.html) from the Aptible Dashboard.

# Deploying the template

<Info>
  Prerequisite: Ensure you have [Git](https://git-scm.com/downloads) installed.
</Info>

Using the [Deploy Code](https://app.aptible.com/create) tool in the Aptible Dashboard, you can deploy the **Ruby on Rails Template**. The tool will guide you through the following:

<Steps>
  <Step title="Deploy with Git Push">
    <img alt="" />
  </Step>

  <Step title="Add an SSH key">
    <img alt="" />

    If you have not done so already, you will be prompted to set up an [SSH key](/docs/core-concepts/security-compliance/authentication/ssh-keys#ssh-keys).
  </Step>

  <Step title="Environment Setup">
    <img alt="" />

    Select your [stack](/docs/core-concepts/architecture/stacks) to deploy your resources. This will determine what region your resources are deployed to. Then, name the [environment](/docs/core-concepts/architecture/environments) your resources will be grouped into.
  </Step>

  <Step title="Prepare the template">
    <img alt="" />

    Select `Ruby on Rails Template` for deployment, and follow the command-line instructions.
  </Step>

  <Step title="Fill environment variables and deploy!">
    <img alt="" />

    Aptible will automatically fill this template's required databases, services, and app's configuration with environment variable keys for you to fill with values. Once complete, save and deploy the code!
  </Step>

  <Step title="View logs in real time">
    <img alt="" />
  </Step>

  <Step title="Expose your app to the internet">
    <img alt="" />

    Now that your code is deployed, it's time to expose your app to the internet. Select the service that needs an [endpoint](/docs/core-concepts/apps/connecting-to-apps/app-endpoints/overview), and Aptible will automatically provision a managed endpoint.
  </Step>

  <Step title="View your deployed app 🎉" icon="party-horn">
    <img alt="" />
  </Step>
</Steps>

# Continue your journey

<Card title="Deploy custom code" icon="books" href="https://www.aptible.com/docs/custom-code-quickstart">
  Read our guide for deploying custom code on Aptible.
</Card>


# Aptible Documentation
Source: https://www.aptible.com/docs/getting-started/home

Aptible gives your team one place to deploy web apps and databases and govern AI usage, with security & compliance guardrails built-in.

## Deploy your first web app

Easily deploy code as Aptible web apps via Docker or Git.

<CardGroup>
  <Card title="Deploy your code" icon="globe" href="https://www.aptible.com/docs/custom-code-quickstart">
    <Badge>Custom Code</Badge>
  </Card>

  <Card title="Ruby Template" href="https://www.aptible.com/docs/ruby-quickstart" icon={<svg width="30" height="30" viewBox="0 0 256 255" xmlns="http://www.w3.org/2000/svg"><path d="M197.467 167.764l-145.52 86.41 188.422-12.787L254.88 51.393l-57.414 116.37z" fill="#CC342D"/><path d="M240.677 241.257L224.482 129.48l-44.113 58.25 60.308 53.528z" fill="#A11401"/><path d="M240.896 241.257l-118.646-9.313-69.674 21.986 188.32-12.673z" fill="#A11401"/><path d="M52.744 253.955l29.64-97.1L17.16 170.8l35.583 83.154z" fill="#E05A4D"/><path d="M180.358 188.05L153.085 81.226l-78.047 73.16 105.32 33.666z" fill="#CC342D"/><path d="M248.693 82.73l-73.777-60.256-20.544 66.418 94.321-6.162z" fill="#E05A4D"/><path d="M214.191.99L170.8 24.97 143.424.669l70.767.322z" fill="#CC342D"/><path d="M2.496 129.48l14.794 41.963 64.283-14.422 73.39-68.207 20.712-65.787L143.063 0 87.618 20.75C70.149 37 36.252 69.146 35.03 69.75c-1.21.618-22.384 40.639-32.534 59.73z" fill="#fff"/><path d="M54.442 54.094c37.86-37.538 86.667-59.716 105.397-40.818 18.72 18.898-1.132 64.823-38.992 102.349-37.86 37.525-86.062 60.925-104.78 42.027-18.73-18.885.515-66.032 38.375-103.558z" fill="#CC342D"/><path d="M52.744 253.916l29.408-97.409 97.665 31.376c-35.312 33.113-74.587 61.106-127.073 66.033z" fill="#9B1209"/><path d="M155.092 88.622l25.073 99.313c29.498-31.016 55.972-64.36 68.938-105.603l-94.01 6.29z" fill="#AA1401"/><path d="M248.847 82.833c10.035-30.282 12.35-73.725-34.966-81.791l-38.825 21.445 73.791 60.346z" fill="#B31000"/><path d="M0 202.935c1.39 49.979 37.448 50.724 52.808 51.162l-35.48-82.86L0 202.935z" fill="#9E1209"/></svg>}>
    <Badge>Sample Code</Badge>
  </Card>

  <Card
    title="NodeJS Template"
    href="https://www.aptible.com/docs/node-js-quickstart"
    icon={
<svg xmlns="http://www.w3.org/2000/svg" width="30" height="30" viewBox="0 0 58 64" fill="none">
<path d="M26.3201 0.681001C27.9201 -0.224999 29.9601 -0.228999 31.5201 0.681001L55.4081 14.147C56.9021 14.987 57.9021 16.653 57.8881 18.375V45.375C57.8981 47.169 56.8001 48.871 55.2241 49.695L31.4641 63.099C30.6514 63.5481 29.7333 63.7714 28.8052 63.7457C27.877 63.7201 26.9727 63.4463 26.1861 62.953L19.0561 58.833C18.5701 58.543 18.0241 58.313 17.6801 57.843C17.9841 57.435 18.5241 57.383 18.9641 57.203C19.9561 56.887 20.8641 56.403 21.7761 55.891C22.0061 55.731 22.2881 55.791 22.5081 55.935L28.5881 59.451C29.0221 59.701 29.4621 59.371 29.8341 59.161L53.1641 45.995C53.4521 45.855 53.6121 45.551 53.5881 45.235V18.495C53.6201 18.135 53.4141 17.807 53.0881 17.661L29.3881 4.315C29.2515 4.22054 29.0894 4.16976 28.9234 4.16941C28.7573 4.16905 28.5951 4.21912 28.4581 4.313L4.79207 17.687C4.47207 17.833 4.25207 18.157 4.29207 18.517V45.257C4.26407 45.573 4.43207 45.871 4.72207 46.007L11.0461 49.577C12.2341 50.217 13.6921 50.577 15.0001 50.107C15.5725 49.8913 16.0652 49.5058 16.4123 49.0021C16.7594 48.4984 16.9443 47.9007 16.9421 47.289L16.9481 20.709C16.9201 20.315 17.2921 19.989 17.6741 20.029H20.7141C21.1141 20.019 21.4281 20.443 21.3741 20.839L21.3681 47.587C21.3701 49.963 20.3941 52.547 18.1961 53.713C15.4881 55.113 12.1401 54.819 9.46407 53.473L2.66407 49.713C1.06407 48.913 -0.00993076 47.185 6.9243e-05 45.393V18.393C0.0067219 17.5155 0.247969 16.6557 0.698803 15.9027C1.14964 15.1498 1.79365 14.5312 2.56407 14.111L26.3201 0.681001ZM33.2081 19.397C36.6621 19.197 40.3601 19.265 43.4681 20.967C45.8741 22.271 47.2081 25.007 47.2521 27.683C47.1841 28.043 46.8081 28.243 46.4641 28.217C45.4641 28.215 44.4601 28.231 43.4561 28.211C43.0301 28.227 42.7841 27.835 42.7301 27.459C42.4421 26.179 41.7441 24.913 40.5401 24.295C38.6921 23.369 36.5481 23.415 34.5321 23.435C33.0601 23.515 31.4781 23.641 30.2321 24.505C29.2721 25.161 28.9841 26.505 29.3261 27.549C29.6461 28.315 30.5321 28.561 31.2541 28.789C35.4181 29.877 39.8281 29.789 43.9141 31.203C45.6041 31.787 47.2581 32.923 47.8381 34.693C48.5941 37.065 48.2641 39.901 46.5781 41.805C45.2101 43.373 43.2181 44.205 41.2281 44.689C38.5821 45.279 35.8381 45.293 33.1521 45.029C30.6261 44.741 27.9981 44.077 26.0481 42.357C24.3801 40.909 23.5681 38.653 23.6481 36.477C23.6681 36.109 24.0341 35.853 24.3881 35.883H27.3881C27.7921 35.855 28.0881 36.203 28.1081 36.583C28.2941 37.783 28.7521 39.083 29.8161 39.783C31.8681 41.107 34.4421 41.015 36.7901 41.053C38.7361 40.967 40.9201 40.941 42.5101 39.653C43.3501 38.919 43.5961 37.693 43.3701 36.637C43.1241 35.745 42.1701 35.331 41.3701 35.037C37.2601 33.737 32.8001 34.209 28.7301 32.737C27.0781 32.153 25.4801 31.049 24.8461 29.351C23.9601 26.951 24.3661 23.977 26.2321 22.137C28.0321 20.307 30.6721 19.601 33.1721 19.349L33.2081 19.397Z" fill="#8CC84B"/></svg>
}
  >
    <Badge>Sample Code</Badge>
  </Card>

  <Card
    title="Django Template"
    href="https://www.aptible.com/docs/python-quickstart"
    icon={
<svg width="30" height="30" viewBox="0 0 256 326" xmlns="http://www.w3.org/2000/svg" preserveAspectRatio="xMinYMin meet"><g fill="#2BA977"><path d="M114.784 0h53.278v244.191c-27.29 5.162-47.38 7.193-69.117 7.193C33.873 251.316 0 222.245 0 166.412c0-53.795 35.93-88.708 91.608-88.708 8.64 0 15.222.68 23.176 2.717V0zm1.867 124.427c-6.24-2.038-11.382-2.717-17.965-2.717-26.947 0-42.512 16.437-42.512 45.243 0 28.046 14.88 43.532 42.17 43.532 5.896 0 10.696-.332 18.307-1.351v-84.707z"/><path d="M255.187 84.26v122.263c0 42.105-3.154 62.353-12.411 79.81-8.64 16.783-20.022 27.366-43.541 39.055l-49.438-23.297c23.519-10.93 34.901-20.588 42.17-35.327 7.61-15.072 10.01-32.529 10.01-78.445V84.261h53.21zM196.608 0h53.278v54.135h-53.278V0z"/></g></svg>
}
  >
    <Badge>Sample Code</Badge>
  </Card>

  <Card
    title="Laravel Template"
    href="https://www.aptible.com/docs/php-quickstart"
    icon={
<svg height="30" viewBox="0 -.11376601 49.74245785 51.31690859" width="30" xmlns="http://www.w3.org/2000/svg"><path d="m49.626 11.564a.809.809 0 0 1 .028.209v10.972a.8.8 0 0 1 -.402.694l-9.209 5.302v10.509c0 .286-.152.55-.4.694l-19.223 11.066c-.044.025-.092.041-.14.058-.018.006-.035.017-.054.022a.805.805 0 0 1 -.41 0c-.022-.006-.042-.018-.063-.026-.044-.016-.09-.03-.132-.054l-19.219-11.066a.801.801 0 0 1 -.402-.694v-32.916c0-.072.01-.142.028-.21.006-.023.02-.044.028-.067.015-.042.029-.085.051-.124.015-.026.037-.047.055-.071.023-.032.044-.065.071-.093.023-.023.053-.04.079-.06.029-.024.055-.05.088-.069h.001l9.61-5.533a.802.802 0 0 1 .8 0l9.61 5.533h.002c.032.02.059.045.088.068.026.02.055.038.078.06.028.029.048.062.072.094.017.024.04.045.054.071.023.04.036.082.052.124.008.023.022.044.028.068a.809.809 0 0 1 .028.209v20.559l8.008-4.611v-10.51c0-.07.01-.141.028-.208.007-.024.02-.045.028-.068.016-.042.03-.085.052-.124.015-.026.037-.047.054-.071.024-.032.044-.065.072-.093.023-.023.052-.04.078-.06.03-.024.056-.05.088-.069h.001l9.611-5.533a.801.801 0 0 1 .8 0l9.61 5.533c.034.02.06.045.09.068.025.02.054.038.077.06.028.029.048.062.072.094.018.024.04.045.054.071.023.039.036.082.052.124.009.023.022.044.028.068zm-1.574 10.718v-9.124l-3.363 1.936-4.646 2.675v9.124l8.01-4.611zm-9.61 16.505v-9.13l-4.57 2.61-13.05 7.448v9.216zm-36.84-31.068v31.068l17.618 10.143v-9.214l-9.204-5.209-.003-.002-.004-.002c-.031-.018-.057-.044-.086-.066-.025-.02-.054-.036-.076-.058l-.002-.003c-.026-.025-.044-.056-.066-.084-.02-.027-.044-.05-.06-.078l-.001-.003c-.018-.03-.029-.066-.042-.1-.013-.03-.03-.058-.038-.09v-.001c-.01-.038-.012-.078-.016-.117-.004-.03-.012-.06-.012-.09v-21.483l-4.645-2.676-3.363-1.934zm8.81-5.994-8.007 4.609 8.005 4.609 8.006-4.61-8.006-4.608zm4.164 28.764 4.645-2.674v-20.096l-3.363 1.936-4.646 2.675v20.096zm24.667-23.325-8.006 4.609 8.006 4.609 8.005-4.61zm-.801 10.605-4.646-2.675-3.363-1.936v9.124l4.645 2.674 3.364 1.937zm-18.422 20.561 11.743-6.704 5.87-3.35-8-4.606-9.211 5.303-8.395 4.833z" fill="#ff2d20"/></svg>
}
  >
    <Badge>Sample Code</Badge>
  </Card>

  <Card title="Python Template" href="https://www.aptible.com/docs/deploy-demo-app" icon={<svg width="30" height="30" viewBox="0 0 256 255" xmlns="http://www.w3.org/2000/svg"><path d="M126.916.072c-64.832 0-60.784 28.115-60.784 28.115l.072 29.128h61.868v8.745H41.631S.145 61.355.145 126.77c0 65.417 36.21 63.097 36.21 63.097h21.61v-30.356s-1.165-36.21 35.632-36.21h61.362s34.475.557 34.475-33.319V33.97S194.67.072 126.916.072zM92.802 19.66a11.12 11.12 0 0 1 11.13 11.13 11.12 11.12 0 0 1-11.13 11.13 11.12 11.12 0 0 1-11.13-11.13 11.12 11.12 0 0 1 11.13-11.13z" fill="#3776AB"/><path d="M128.757 254.126c64.832 0 60.784-28.115 60.784-28.115l-.072-29.127H127.6v-8.745h86.441s41.486 4.705 41.486-60.712c0-65.416-36.21-63.096-36.21-63.096h-21.61v30.355s1.165 36.21-35.632 36.21h-61.362s-34.475-.557-34.475 33.32v56.013s-5.235 33.897 62.518 33.897zm34.114-19.586a11.12 11.12 0 0 1-11.13-11.13 11.12 11.12 0 0 1 11.13-11.131 11.12 11.12 0 0 1 11.13 11.13 11.12 11.12 0 0 1-11.13 11.13z" fill="#FFD43B"/></svg>}>
    <Badge>Sample Code</Badge>
  </Card>
</CardGroup>

## Manage AI usage for teams and agents

Governance and controls for how your team uses AI.

<CardGroup>
  <Card title="LLM Gateway" icon="brain-circuit" href="https://www.aptible.com/docs/llm-gateway">
    One compliant API for 400+ models, with access policies, spend limits, and audit logs.
  </Card>

  <Card title="MCP Gateway" icon="shield-halved" href="/mcp-gateway">
    Access controls and audit logs for every MCP server your team and agents use.
  </Card>
</CardGroup>

## Provision managed databases

Instantly provision secure, encrypted databases, managed 24x7 by the Aptible SRE team.

<CardGroup>
  <Card title="Elasticsearch" icon={<svg xmlns="http://www.w3.org/2000/svg" width="30" height="30" viewBox="0 0 48 48"><path fill="#29b6f6" d="M37,24c0-3.314-2.686-6-6-6H5.918C5.323,19.894,5,21.909,5,24s0.323,4.106,0.918,6H31 C34.314,30,37,27.314,37,24z"/><path fill="#4db6ac" d="M25,44c6.524,0,12.305-3.133,15.954-7.968C38.835,34.151,36.055,33,33,33H7.157 C10.453,39.52,17.196,44,25,44z"/><path fill="#ffca28" d="M25,4C17.195,4,10.453,8.48,7.157,15H33c3.051,0,5.828-1.148,7.946-3.024 C37.299,7.138,31.525,4,25,4z"/><path fill="#f9a825" d="M22.073,15c-1.513-3.367-3.845-6.288-6.747-8.501C11.817,8.443,8.957,11.412,7.143,15H22.073z"/><path fill="#009688" d="M15.326,41.501c2.902-2.213,5.233-5.134,6.747-8.501H7.143 C8.957,36.588,11.817,39.557,15.326,41.501z"/><path fill="#212121" d="M5.928,18C5.332,19.895,5,21.907,5,24s0.332,4.105,0.928,6h17.234C23.703,28.092,24,26.081,24,24 s-0.297-4.092-0.837-6H5.928z"/></svg>} href="https://www.aptible.com/docs/elasticsearch" />

  <Card title="InfluxDB" icon={<svg xmlns="http://www.w3.org/2000/svg" width="30" height="30" viewBox="0 0 128 128"><path style={{fillRule:"evenodd",fill:"#020a47",fillOpacity:1}} d="m94.543 87.625 29.379-6.75a3.35 3.35 0 0 0 1.258-.543 3.358 3.358 0 0 0 1.383-2.305c.058-.46.019-.925-.114-1.37L113.957 22.34a3.499 3.499 0 0 0-1.59-2.14 3.49 3.49 0 0 0-2.633-.391l-29.37 6.75c-.887.23-1.65.8-2.118 1.593a3.452 3.452 0 0 0-.383 2.625L90.32 85.094a3.499 3.499 0 0 0 1.59 2.14c.79.477 1.738.618 2.633.391Zm-10.125 33.566 35.621-33.054c1.344-1.36 1.004-2.196-.844-1.528l-24.484 5.575a6.222 6.222 0 0 0-2.715 1.46 6.221 6.221 0 0 0-1.676 2.586l-7.425 23.954c-.508 1.855.168 2.363 1.523 1.007Zm-64.992-10.789 53.344 16.52c.91.172 1.851.012 2.656-.45a3.947 3.947 0 0 0 1.734-2.07l8.938-28.68a3.48 3.48 0 0 0 .117-1.378 3.492 3.492 0 0 0-.418-1.317 3.473 3.473 0 0 0-.89-1.058 3.562 3.562 0 0 0-1.227-.633L30.336 74.973a3.545 3.545 0 0 0-2.695.304 3.57 3.57 0 0 0-1.696 2.118l-8.879 28.62a3.556 3.556 0 0 0 .278 2.68 3.547 3.547 0 0 0 2.082 1.707ZM2.2 51.7l10.816 47.452c.336 1.856 1.207 1.856 1.68 0l7.425-23.949a6.709 6.709 0 0 0 .031-3.113 6.783 6.783 0 0 0-1.37-2.793L3.721 50.852c-1.183-1.395-2.066-1.008-1.523.847ZM43.906.973 3.046 38.875a3.47 3.47 0 0 0-.168 4.848l20.43 22.144a3.483 3.483 0 0 0 2.415 1.098 3.48 3.48 0 0 0 2.484-.926l40.848-37.965a3.446 3.446 0 0 0 .172-4.847L48.832 1.094A3.48 3.48 0 0 0 47.722.3a3.467 3.467 0 0 0-1.326-.3 3.419 3.419 0 0 0-1.34.238 3.435 3.435 0 0 0-1.149.735Zm39.496 85.804c1.864.508 3.035-.496 2.54-2.422L74.124 33.082c-.508-1.855-2.035-2.363-3.375-1.02L32.258 67.895c-1.352 1.343-1.016 2.859.836 3.367Zm20.09-71.515L56.898.972c-1.851-.511-2.187.169-.675 1.684l17.054 18.387a6.549 6.549 0 0 0 2.7 1.527 6.58 6.58 0 0 0 3.093.11l24.485-5.563c1.8-.508 1.8-1.355-.063-1.855Zm0 0"/></svg>} href="https://www.aptible.com/docs/influxdb" />

  <Card title="MySQL" icon="https://www.vectorlogo.zone/logos/mysql/mysql-icon.svg" href="https://www.aptible.com/docs/mysql" />

  <Card title="PostgreSQL" icon={<svg xmlns="http://www.w3.org/2000/svg" width="30" height="30" viewBox="0 0 48 48"><path fill="#fff" d="M44.083,29.79c-0.183-0.829-0.935-1.796-2.452-1.796c-0.31,0-0.649,0.039-1.035,0.119c-0.708,0.146-1.311,0.217-1.842,0.241c4.133-7.04,6.816-16.819,4.159-20.214c-3.501-4.473-8.214-5.141-10.711-5.141L31.967,3c-0.929,0.015-1.893,0.129-2.863,0.339l-3.583,0.774C25.033,4.052,24.536,4.009,24.018,4l-0.03,0l-0.016,0l-0.152-0.001c-1.593,0-3.046,0.338-4.341,0.973l-1.251-0.493c-1.72-0.678-4.308-1.485-6.868-1.485c-0.144,0-0.287,0.003-0.431,0.008C8.407,3.093,6.241,4.05,4.664,5.769C2.696,7.915,1.8,11.054,2.003,15.1C2.013,15.309,4.461,36,11.4,36h0.025l0.064-0.001c0.901-0.022,1.76-0.384,2.563-1.077c0.613,0.46,1.406,0.732,2.145,0.84c0.488,0.115,1.366,0.278,2.418,0.278c1.284,0,2.442-0.263,3.44-0.738c-0.001,0.88-0.006,1.994-0.016,3.418l-0.001,0.075l0.005,0.075c0.097,1.419,0.342,2.698,0.711,3.701c1.051,2.859,2.866,4.434,5.111,4.434c0.093,0,0.188-0.003,0.284-0.009c1.846-0.114,3.717-1.151,5.004-2.772c1.393-1.755,1.715-3.607,1.839-5.026L35,39.111v-0.088v-4.079l0.103,0.01l0.436,0.038l0.042,0.004l0.042,0.002c0.124,0.006,0.252,0.008,0.381,0.008c1.507,0,3.362-0.391,4.616-0.974C41.819,33.476,44.559,31.948,44.083,29.79z"/><path fill="#0277bd" d="M33,34c0-0.205,0.012-0.376,0.018-0.565C33.008,33.184,33,33,33,33s0.012-0.009,0.032-0.022c0.149-2.673,0.886-3.703,1.675-4.29c-0.11-0.153-0.237-0.318-0.356-0.475c-0.333-0.437-0.748-0.979-1.192-1.674l-0.082-0.158c-0.067-0.164-0.229-0.447-0.435-0.819c-1.183-2.14-3.645-6.592-1.96-9.404c0.738-1.232,2.122-1.942,4.121-2.117C33.986,11.718,30.925,6.115,23.985,6c-0.002,0-0.004,0-0.006,0c-6.041-0.098-8.026,5.392-8.672,8.672c0.89-0.377,1.906-0.606,2.836-0.606c0.014,0,0.029,0,0.043,0c2.29,0.017,3.865,1.239,4.323,3.354c0.335,1.552,0.496,2.91,0.492,4.153c-0.01,2.719-0.558,4.149-1.042,5.411l-0.154,0.408c-0.124,0.334-0.255,0.645-0.379,0.937c-0.126,0.298-0.237,0.563-0.318,0.802c0.484,0.11,0.864,0.265,1.125,0.38l0.151,0.066c0.047,0.02,0.094,0.043,0.137,0.069c0.848,0.516,1.376,1.309,1.489,2.233c0.061,0.498,0.051,3.893,0.03,6.855c0.087,1.285,0.305,2.364,0.593,3.146c0.409,1.114,1.431,3.241,3.394,3.119c1.37-0.085,2.687-0.919,3.561-2.019c0.938-1.181,1.284-2.487,1.414-3.958V34z"/><path fill="#0277bd" d="M15.114 28.917c-1.613-1.683-2.399-3.947-2.104-6.056.285-2.035.124-4.027.037-5.098-.029-.357-.048-.623-.047-.77 0-.008.002-.015.003-.023 0-.004-.002-.007-.002-.011.121-3.021 1.286-7.787 4.493-10.62C15.932 5.724 13.388 4.913 11 5 7.258 5.136 3.636 7.724 4 15c.137 2.73 3.222 19.103 7.44 19 .603-.015 1.229-.402 1.872-1.176 1.017-1.223 2.005-2.332 2.708-3.104C15.705 29.481 15.401 29.217 15.114 28.917zM37.023 14.731c.015.154.002.286-.022.408.031.92-.068 1.813-.169 2.677-.074.636-.15 1.293-.171 1.952-.021.645.07 1.282.166 1.956.225 1.578.459 3.359-.765 5.437.225.296.423.571.581.837 4.61-7.475 6.468-16.361 4.695-18.626C38.655 5.944 34.941 4.952 31.999 5c-.921.015-1.758.139-2.473.294C34.602 7.754 36.863 13.026 37.023 14.731zM41 30.071c-2.665.55-3.947.257-4.569-.126-.1.072-.2.133-.293.19-.372.225-.961.583-1.105 2.782.083.016.156.025.246.044L35.714 33c1.32.06 3.049-.31 4.063-.781C41.962 31.205 43.153 29.627 41 30.071zM22.023 32.119c-.037-.298-.198-.539-.492-.732l-.108-.047C21.062 31.181 20.653 31 20 31h-.004c-.127.01-.253.019-.38.019-.052 0-.103-.007-.155-.009-.474.365-1.148.647-2.816.99-2.98.759-1.221 1.655-.078 1.794 1.106.277 3.735.614 5.481-.809C22.043 32.537 22.035 32.229 22.023 32.119z"/><path fill="#0277bd" d="M20.681 18.501c-.292.302-.753.566-1.262.484-.828-.134-1.463-1.133-1.417-1.508h0c.044-.374.751-.569 1.578-.435.287.047.548.128.768.228-.32-.688-.899-1.085-1.782-1.182-1.565-.174-3.226.644-3.56 1.097.007.11.02.251.033.417.093 1.147.265 3.284-.05 5.537-.208 1.485.393 3.169 1.567 4.395.757.79 1.641 1.29 2.513 1.438.111-.478.309-.944.513-1.425.113-.265.233-.547.346-.852l.162-.427c.443-1.155.9-2.35.909-4.703C21.003 20.66 20.892 19.627 20.681 18.501zM34.847 22.007c-.104-.729-.211-1.484-.185-2.303.023-.742.105-1.442.184-2.119.062-.533.11-1.045.138-1.55-1.289.107-2.145.479-2.551 1.108.168-.057.358-.102.568-.129.892-.116 1.543.141 1.618.637.055.363-.253.705-.388.836-.277.269-.626.442-.981.488-.064.008-.129.012-.192.012-.353 0-.69-.121-.949-.3.112 1.973 1.567 4.612 2.283 5.907.153.277.271.498.369.688C35.154 24.163 35.009 23.143 34.847 22.007z"/></svg>} href="https://www.aptible.com/docs/postgresql" />

  <Card title="RabbitMQ" icon="https://www.rabbitmq.com/assets/files/rabbitmq-logo-e91cacd38fcef5219149bc5cfa10b384.svg" href="https://www.aptible.com/docs/rabbitmq" />

  <Card title="Redis" icon={<svg xmlns="http://www.w3.org/2000/svg" width="30" height="30" viewBox="0 0 48 48"><path fill="#b71c1c" d="M45,29.316c0-0.637-1.686-1.153-3.769-1.153c-1.812,0-3.32,0.391-3.683,0.911	c-3.586-1.694-7.173-3.388-10.759-5.083c-1.248-0.59-2.673-0.584-3.918,0.014c-3.818,1.837-7.636,3.674-11.454,5.511	c-0.864-0.126-1.907-0.201-3.032-0.201C5.408,29.316,3,29.832,3,30.469v3.46c0,0.033,0.033,0.064,0.045,0.096	c-0.146,0.555,0.07,1.205,0.649,1.478c5.641,2.665,11.281,5.329,16.922,7.994c1.432,0.677,3.068,0.671,4.496-0.016	c6.442-3.1,12.884-6.199,19.327-9.299c0.484-0.233,0.651-0.786,0.509-1.247C44.971,32.882,45,32.83,45,32.775V29.316z"/><path fill="#e53935" d="M20.616,39.158c-5.641-2.522-11.281-5.044-16.922-7.566c-0.922-0.412-0.926-1.727-0.007-2.146	c6.395-2.912,12.789-5.824,19.184-8.736c1.244-0.567,2.67-0.572,3.918-0.014c5.881,2.63,11.763,5.259,17.644,7.889	c0.754,0.337,0.758,1.414,0.006,1.756c-6.442,2.934-12.884,5.868-19.327,8.801C23.684,39.792,22.048,39.798,20.616,39.158z"/><path fill="#b71c1c" d="M45,21.675c0-0.637-1.686-1.153-3.769-1.153c-1.812,0-3.32,0.391-3.683,0.911	c-3.586-1.694-7.173-3.388-10.759-5.083c-1.248-0.59-2.673-0.584-3.918,0.014c-3.818,1.837-7.636,3.674-11.454,5.511	c-0.864-0.126-1.907-0.201-3.032-0.201C5.408,21.675,3,22.192,3,22.829v3.46c0,0.033,0.033,0.064,0.045,0.096	c-0.146,0.555,0.07,1.205,0.649,1.478c5.641,2.665,11.281,5.329,16.922,7.994c1.432,0.677,3.068,0.671,4.496-0.016	c6.442-3.1,12.884-6.199,19.327-9.299c0.484-0.233,0.651-0.786,0.509-1.247C44.971,25.242,45,25.19,45,25.135V21.675z"/><path fill="#e53935" d="M20.616,31.517c-5.641-2.522-11.281-5.044-16.922-7.566c-0.922-0.412-0.926-1.727-0.007-2.146	c6.395-2.912,12.789-5.824,19.184-8.736c1.244-0.567,2.67-0.572,3.918-0.014c5.881,2.63,11.763,5.259,17.644,7.889	c0.754,0.337,0.758,1.414,0.006,1.756c-6.442,2.934-12.884,5.868-19.327,8.801C23.684,32.152,22.048,32.158,20.616,31.517z"/><path fill="#b71c1c" d="M45,14.035c0-0.637-1.686-1.153-3.769-1.153c-1.812,0-3.32,0.391-3.683,0.911	c-3.586-1.694-7.173-3.388-10.759-5.083c-1.248-0.59-2.673-0.584-3.918,0.014c-3.818,1.837-7.636,3.674-11.454,5.511	c-0.864-0.126-1.907-0.201-3.032-0.201C5.408,14.035,3,14.551,3,15.188v3.46c0,0.033,0.033,0.064,0.045,0.096	c-0.146,0.555,0.07,1.205,0.649,1.478c5.641,2.665,11.281,5.329,16.922,7.994c1.432,0.677,3.068,0.671,4.496-0.016	c6.442-3.1,12.884-6.199,19.327-9.299c0.484-0.233,0.651-0.786,0.509-1.247C44.971,17.601,45,17.549,45,17.494V14.035z"/><path fill="#e53935" d="M20.616,23.877c-5.641-2.522-11.281-5.044-16.922-7.566c-0.922-0.412-0.926-1.727-0.007-2.146	c6.395-2.912,12.789-5.824,19.184-8.736c1.244-0.567,2.67-0.572,3.918-0.014c5.881,2.63,11.763,5.259,17.644,7.889	c0.754,0.337,0.758,1.414,0.006,1.756c-6.442,2.934-12.884,5.868-19.327,8.801C23.684,24.512,22.048,24.517,20.616,23.877z"/><path fill="#fff" d="M18.748,14.741c-0.002,1.042-2.762,2.057-5.093,2.086c-2.419,0.03-5.273-0.993-5.282-2.051	c-0.009-1.061,2.842-2.161,5.311-2.135C16.017,12.665,18.751,13.703,18.748,14.741z"/><path fill="#fff" d="M17.038,18.471c2.393,1.022,4.785,2.045,7.178,3.067c1.054-1.56,2.108-3.12,3.162-4.68	C23.931,17.396,20.485,17.934,17.038,18.471z"/><path fill="#fff" d="M21.86,9.775c-1.101,0.401-2.203,0.801-3.304,1.202c1.507,0.132,3.015,0.264,4.522,0.395	c0.48,0.796,0.959,1.592,1.439,2.387c0.295-0.722,0.59-1.444,0.885-2.166c1.286-0.1,2.572-0.2,3.858-0.3	c-0.997-0.419-1.994-0.839-2.991-1.259c0.254-0.608,0.508-1.216,0.762-1.825c-0.97,0.29-1.939,0.58-2.909,0.87	c-1.07-0.422-2.14-0.843-3.21-1.265C21.228,8.468,21.544,9.122,21.86,9.775z"/><path fill="#b71c1c" d="M27.267,14.619c2.271-0.906,4.543-1.813,6.814-2.719c1.962,0.834,3.924,1.668,5.886,2.502	c-2.202,0.876-4.403,1.752-6.605,2.629C31.331,16.226,29.299,15.423,27.267,14.619z"/><path fill="#a01c1c" d="M34.082,11.963c-0.005,1.596-0.01,3.191-0.015,4.787c1.967-0.783,3.934-1.565,5.901-2.348	C38.006,13.589,36.044,12.776,34.082,11.963z"/></svg>} href="https://www.aptible.com/docs/redis" />

  <Card title="SFTP" icon="file" href="https://www.aptible.com/docs/sftp" />

  <Card title="See all" icon="grid" href="https://www.aptible.com/docs/core-concepts/managed-databases/supported-databases/overview" />
</CardGroup>

## Secure, compliant infrastructure

All infrastructure on Aptible comes with security best practices in place and out-of-the-box support for major compliance frameworks.

<CardGroup>
  <Card title="HIPAA" icon="shield-check" href="https://www.aptible.com/docs/core-concepts/security-compliance/compliance-frameworks/hipaa" />

  <Card title="HITRUST" icon="shield-check" href="https://www.aptible.com/docs/core-concepts/security-compliance/compliance-frameworks/hitrust" />

  <Card title="SOC 2" icon="shield-check" href="https://www.aptible.com/docs/core-concepts/security-compliance/compliance-frameworks/soc2" />

  <Card title="PCI" icon="shield-check" href="https://www.aptible.com/docs/core-concepts/security-compliance/compliance-frameworks/pci" />

  <Card title="GDPR" icon="shield-check" href="https://trust.aptible.com/" />

  <Card title="PIPEDA" icon="shield-check" href="https://www.aptible.com/docs/core-concepts/security-compliance/compliance-frameworks/pipeda" />
</CardGroup>

## Use developer tools & integrations

<CardGroup>
  <Card title="Install the Aptible CLI" href="https://www.aptible.com/docs/reference/aptible-cli/overview">
    ```text theme={null}
     brew install --cask aptible
    ```
  </Card>

  <Card title="Browse tools & integrations" href="https://www.aptible.com/docs/core-concepts/integrations/overview" />
</CardGroup>


# Introduction to Aptible
Source: https://www.aptible.com/docs/getting-started/introduction

Learn what Aptible is and why scaling companies use it to host their apps and data in the cloud

## Overview

Aptible is a [Platform as a Service](/docs/reference/glossary#paas) (PaaS) used by companies that want their development teams to focus on their product, not managing infrastructure.

Aptible provides everything you need to ship and scale compliant applications:

* [Deploy code in seconds](/docs/core-concepts/apps/deploying-apps/overview) with seamless [CI/CD integration](/docs/how-to-guides/app-guides/how-to-deploy-aptible-ci-cd)
* [Provision databases](/docs/core-concepts/managed-databases/provisioning-databases) on dedicated, non-shared infrastructure with 8 database types
* Enforce and prove compliance requirements automatically with the [Security & Compliance Dashboard](/docs/core-concepts/security-compliance/security-compliance-dashboard/overview)
* Continuously capture and retain all infrastructure activity with [audit logs](/docs/core-concepts/observability/activity/overview)
* Built-in expertise with 24/7 engineering coverage from our [SRE team](/docs/core-concepts/architecture/reliability-division)
* Flexibility to use the [Aptible CLI](/docs/reference/aptible-cli/overview), [Dashboard](https://app.aptible.com), or [Terraform provider](/docs/reference/terraform)

## Our Story

Our journey began in **2013**, a time when HIPAA, with all its complexities, was still relatively new and challenging to decipher. As we approached September 2013, an impending deadline loomed large: the HIPAA Omnibus Rule was set to take effect, mandating thousands of digital health companies to comply with HIPAA basically overnight.

Recognizing this imminent need, Aptible embarked on a mission to simplify HIPAA for developers in healthcare, from solo developers at startups to large-scale development teams who lacked the time or resources to delve into the compliance space. We brought a platform to the market that made HIPAA compliance achievable from day 1. Soon after, we expanded our scope to support HITRUST, SOC 2, ISO 27001, and more, establishing ourselves as the **go-to PaaS for digital health companies**.

As we continued to evolve our platform, we realized we had created something exceptional: a platform that streamlines security and compliance, offers reliable and high-performance infrastructure as the default, and allows for easy resource scaling -- with a best-in-class support team providing invaluable infrastructure expertise. It became evident that it could benefit a broader range of companies beyond digital health. This realization led to a pivotal shift in our mission: to **alleviate infrastructure challenges for all dev teams**.

## Apps

An Aptible app is a containerized workload that runs on dedicated AWS infrastructure -- fully isolated, with no shared resources between customers. You bring your code; Aptible handles the rest. Apps support a broad range of languages, frameworks, and runtimes.

Once deployed, every app gets:

* **Isolated Containers** -- on-demand Docker containers, dedicated per-app with no cross-tenant risk; full network isolation is enforced at the infrastructure layer by default
* **Deployment & Releases** -- zero-downtime deployments, instant rollbacks, high-availability by default, and centralized secrets and config management
* **Scaling** -- horizontal and vertical autoscaling, container profiles (General Purpose, Memory Optimized, or CPU Optimized), container efficiency recommendations, and HTTPS endpoints with built-in load balancing and TLS termination

[Read more about Apps →](/docs/core-concepts/apps/overview)

## Databases

Aptible provides fully managed databases on dedicated, non-shared infrastructure. Every database runs in its own isolated environment -- you get the instance, not a slice of one. Aptible supports [8 database types](/docs/core-concepts/managed-databases/overview), including PostgreSQL, MySQL, Redis, and Elasticsearch.

* **Dedicated Infrastructure** -- non-shared database instances with no noisy neighbors or cross-tenant risk; isolation enforced by design, not configuration
* **Security & Access Controls** -- encryption at rest and in transit enforced by default; identity-based permissions control who can connect, tunnel into, and modify databases; every access event is logged and attributable
* **Data Protection** -- automated daily backups with configurable retention, point-in-time recovery, cross-region backup copies, and read/standby replicas
* **Operations** -- patching, monitoring, and maintenance handled by Aptible; in-place version upgrades without reprovisioning; scalable storage and compute on demand

[Read more about Databases →](/docs/core-concepts/managed-databases/overview)

## Security & Compliance

[Our story](#our-story) began with a focus on security and compliance, making us the leading PaaS for regulated industries. We provide developer-friendly infrastructure guardrails and the evidence collection tools to help you pass security audits and maintain compliance -- without slowing down your team.

* **Automated Controls** -- when you deploy on a dedicated stack, you automatically get encryption at rest and in transit, DDoS protection and host hardening, intrusion detection (HIDS), and secure access with granular permissions, MFA, and SSO
* **Evidence Collection** -- the [Security & Compliance Dashboard](/docs/core-concepts/security-compliance/security-compliance-dashboard/overview) provides a unified view of your implemented controls; track compliance readiness scores, review control performance, and generate shareable compliance reports
* **Compliance Documentation** -- HIPAA BAAs, HITRUST Inheritance, and SOC 2 support; access Aptible's certifications and audit reports via the [Trust Center](https://trust.aptible.com/); use [AI Gateway](/docs/core-concepts/ai-gateway) for a HIPAA-eligible path to LLMs with PHI in production

[Read more about Security & Compliance →](/docs/core-concepts/security-compliance/overview)

## Reliability

We believe in reliable infrastructure for all. Aptible is engineered to minimize downtime by default, and makes advanced reliability practices -- like multi-region deployments -- straightforward to implement.

* **Uptime & SLAs** -- 99.98% uptime average with a guaranteed [SLA of 99.95%](https://www.aptible.com/legal/service-level-agreement); 24/7 SRE monitoring with direct access via a shared Slack channel
* **High Availability** -- multi-region support to minimize blast radius from regional outages; high-availability app deployments distributed across availability zones by default
* **Database Reliability** -- automated maintenance and patching; cross-region backup copies for disaster recovery; typical downtime during database scaling operations under 1 minute

[Read more about Reliability →](/docs/core-concepts/architecture/reliability-division)

## Cost Control

Aptible includes built-in tools to help you understand and reduce your infrastructure spend -- without needing to dig through a cloud console.

* **Visibility** -- view estimated monthly costs at the stack, environment, and resource level directly in the UI, so you always know what you're running
* **Optimization** -- container efficiency recommendations identify over- and under-provisioned services with estimated savings; container profiles let you match CPU- or RAM-optimized configurations to your workload; autoscaling reduces idle resource usage; [shared endpoints](/docs/core-concepts/apps/connecting-to-apps/app-endpoints/https-endpoints/shared-endpoints) lower load balancer costs when dedicated endpoints aren't required
* **Expert Support** -- Aptible's infrastructure optimization team is available to review your account and provide cost reduction recommendations at any time

## Developer Tools

Aptible is built to fit into your existing development workflow -- whether you prefer a CLI, a dashboard, or infrastructure-as-code.

* **[Aptible CLI](/docs/reference/aptible-cli/overview)** -- full control over your infrastructure from the terminal; deploy apps, manage databases, stream logs, run one-off commands, and more
* **[Terraform](/docs/reference/terraform)** -- define and manage your entire Aptible infrastructure as code; version-control your environments and automate provisioning
* **[CI/CD Integration](/docs/how-to-guides/app-guides/how-to-deploy-aptible-ci-cd)** -- integrates with any CI/CD platform including GitHub Actions, CircleCI, and GitLab CI
* **[AI Gateway](/docs/core-concepts/ai-gateway)** -- a secure, HIPAA-eligible gateway for using LLMs with PHI in production, with request logging and access controls built in

## Explore More

<CardGroup>
  <Card title="App Deployment" icon="rocket" href="/core-concepts/apps/overview">
    Deploy and operate compliant applications on AWS without operational overhead
  </Card>

  <Card title="Managed Databases" icon="database" href="/core-concepts/managed-databases/overview">
    Production databases with built-in security, backups, and compliance controls
  </Card>

  <Card title="Security & Compliance" icon="shield" href="/core-concepts/security-compliance/overview">
    Secure defaults and access controls for regulated production environments
  </Card>

  <Card title="Observability" icon="chart-line" href="/core-concepts/observability/overview">
    Logs, metrics, and audit trails designed for compliant production systems
  </Card>

  <Card title="AI Gateway" icon="sparkles" href="/core-concepts/ai-gateway">
    A secure gateway for using LLMs with PHI in production environments
  </Card>

  <Card title="Tools & Integrations" icon="plug" href="/how-to-guides/guides-overview">
    Connect Aptible with your existing development workflow
  </Card>
</CardGroup>


# How to access configuration variables during Docker build
Source: https://www.aptible.com/docs/how-to-guides/app-guides/access-config-vars-during-docker-build



By design (for better or worse), Docker doesn't allow setting arbitrary environment variables during the Docker build process: that is only possible when running [Containers](/docs/core-concepts/architecture/containers/overview) after the [Image](/docs/core-concepts/apps/deploying-apps/image/overview) is built.

The rationale for this is that [Dockerfiles](/docs/core-concepts/apps/deploying-apps/image/deploying-with-git/overview) should be fully portable and not tied to any specific environment.

A direct consequence of this design is that your [Configuration](/docs/core-concepts/apps/deploying-apps/configuration) variables, set via [`aptible config:set`](/docs/reference/aptible-cli/cli-commands/cli-config-set), are not available to commands executed during the Docker build.

It's a good idea to follow Docker best practice and avoid depending on Configuration variables in instructions in your Dockerfile, but if you absolutely need to, Aptible provides a workaround: `.aptible.env`.

## `.aptible.env`

When building your image, Aptible injects a `.aptible.env` file at the root of your repository prior to running the Docker build. The file contains your Configuration variables, and can be sourced by a shell.

Here's an example:

```ruby theme={null}
RAILS_ENV=production
DATABASE_URL=postgresql://user:password@host:123/db
```

If needed, you can use this file to access environment variables during your build, like this:

```ruby theme={null}
# Assume that you've already ADDed your repo:
ADD . /app
WORKDIR /app

# The bundle exec rake assets:precompile command
# will run with your configuration
RUN set -a && . /app/.aptible.env && \
        bundle exec rake assets:precompile
```

> ❗️ Do **not** use the `.aptible.env` file outside of Dockerfile instructions. This file is only injected when your image is built, so changes to your configuration will **not** be reflected in the `.aptible.env` file unless you deploy again or rebuild. Outside of your Dockerfile, your configuration variables are accessible in the [Container Environment](/docs/core-concepts/architecture/containers/overview).


# How to define services
Source: https://www.aptible.com/docs/how-to-guides/app-guides/define-services



Learn how to define [services](/docs/core-concepts/apps/deploying-apps/services)

## Implicit Service (CMD)

If your App's [Image](/docs/core-concepts/apps/deploying-apps/image/overview) includes a `CMD` and/or `ENTRYPOINT` declaration, a single implicit `cmd` service will be created for it when you deploy your App.

[Containers](/docs/core-concepts/architecture/containers/overview) for the implicit `cmd` Service will execute the `CMD` your image defines (if you have an `ENTRYPOINT` defined, then the `CMD` will be passed as arguments to the `ENTRYPOINT`).

This corresponds to Docker's behavior when you use `docker run`, so if you've started Containers for your image locally using `docker run my-image`, you can expect Containers started on Aptible to behave identically.

Typically, the `CMD` declaration is something you'd add in your Dockerfile, like so:

```sql theme={null}
FROM alpine:3.5
ADD . /app
CMD ["/app/run"]
```

> 📘 Using an implicit service is recommended if your App only has one Service.

## Explicit Services (Procfiles)

Procfiles are used to define explicit services for an app. They are optional; in the absence of a Procfile, Aptible will fall back to an Implicit Service. Explicit services allow you to specify commands for each service, like `web` or `worker` while implicit services use the `cmd` or `ENTRYPOINT` defined in the image.

### Step 01: Providing a Procfile

There are two ways to provide a Procfile:

* **Deploying via Git Push:**

  If you are deploying via Git, add a file named

  `Procfile`

  at the root of your repository.

* **Deploying via Docker Image:**

  If you are using Docker Image, it must be located at

  `/.aptible/Procfile`

  in your Docker image. See

  [Procfiles and `.aptible.yml` when deploying via Docker image](/docs/core-concepts/apps/deploying-apps/image/deploying-with-docker-image/procfile-aptible-yml-direct-docker-deploy)

  for more information.

> 📘 Note the following when using Procfile:
> **-Procfile syntax:** The [Procfile syntax is standardized](https://ddollar.github.io/foreman/), and consists of a mapping of one or more Service names to commands that should be executed for those Services. The two should be separated by a `:` character.
> **-Procfile commands:** The commands in your Procfile (i.e. the section to the right of the : character) is interpreted differently depending on whether your image has an ENTRYPOINT or not:

### Step 02: Executing your Procfile

#### Images without an `ENTRYPOINT`

If your image does not have an `ENTRYPOINT`, the Procfile will be executed using a shell (`/bin/sh`). This means you can use shell syntax, such as:

```sql theme={null}
web: setup && run "$ENVIRONMENT"
```

**Advanced: PID 1 in your Container is a shell**

> 📘 The following is advanced information. You don't need to understand or leverage this information to use Aptible, but it might be relevant if you want to precisely control the behavior of your Containers. PID 1 is the process that receives signals when your Container is signaled (e.g. PID receives `SIGTERM` when your Container needs to shut down during a deployment). Since a shell is used as the command in your Containers to interpret your Procfile, this means PID 1 will be a shell. Shells don't typically forward signals, which means that when your Containers receive `SIGTERM`, they'll do nothing if a shell is running as PID 1. As a result, running a shell there may not be desirable.

If you'd like to get the shell out of the equation when running your Containers, you can use the exec call, like so:

```sql theme={null}
web: setup && exec run "$ENVIRONMENT"
```

This will replace the shell with the run program as PID 1.

#### Images with an `ENTRYPOINT`

If your image has an `ENTRYPOINT`, Aptible will not use a shell to interpret your Procfile. Instead, your Procfile line is split according to shell rules, then simply passed to your Container's `ENTRYPOINT` as a series of arguments.

For example, if your Procfile looks like this:

```
web: run "$ENVIRONMENT"
```

Then, your `ENTRYPOINT` will receive the **literal** strings `run` and `$ENVIRONMENT` as arguments (i.e. the value for `$ENVIRONMENT` will **not** be interpolated).

This means your Procfile doesn't need to reference commands that exist in your Container: it only means to reference commands that make sense to your `ENTRYPOINT`.

However, it also means that you can't interpolate variables in your Procfile line. If you do need shell processing for interpolation with an `ENTRYPOINT`, here are two options:

**Call a shell from the Procfile**

The simplest option is to alter your `Procfile` to call a shell itself, like so:

```sql theme={null}
web: sh -c 'setup && exec run "$ENVIRONMENT"'
```

**Use a launcher script**

A better approach is to add a launcher script in your Docker image, and delegate shell processing there. To do so, create a file called `/app.sh` in your image, with the following contents, and make it executable:

```sql theme={null}
#!/bin/sh
# Make this executable
# Adjust the commands as needed, of course!
setup && exec run "$ENVIRONMENT"
```

Once you have this launcher script, your Procfile can simply reference the launcher script, which is simpler and more explicit:

```sql theme={null}
web: /app.sh
```

Of course, you can use any name you like: `/app.sh` isn't the only one that works! Just make sure the Procfile references the launcher script.

## Step 03: Scale your services (optionally)

Aptible will automatically provision the services defined in your Procfile into app containers. You can scale services independently via the Aptible Dashboard or Aptible CLI:

```sql theme={null}
aptible apps:scale SERVICE [--container-count COUNT] [--container-size SIZE_MB]
```

When a service is scaled with 2+ containers, the platform will automatically deploy your app containers with high availability.


# How to deploy via Docker Image
Source: https://www.aptible.com/docs/how-to-guides/app-guides/deploy-docker-image

Learn how to deploy your code to Aptible from a Docker Image

## Overview

Aptible lets you deploy via Docker image. Additionally, [Aptible's Terraform Provider](/docs/reference/terraform) currently only supports this deployment method.

This guide will cover the process for deploying via Docker image to Aptible via the CLI, Terraform, or CI/CD.

## Deploying via the CLI

> ⚠️ Prerequisites: Install the [Aptible CLI](/docs/reference/aptible-cli/cli-commands/overview)

### 01: Create an app

Use the `aptible apps:create` to create an [app](/docs/core-concepts/apps/overview). Note the handle you give to the app. We'll refer to it as `$APP_HANDLE`.

### 02: Deploy a Docker image to your app

Use the `aptible deploy` command to deploy a public Docker image to your app like so:

```js theme={null}
aptible deploy --app "$APP_HANDLE" \
        --docker-image httpd:alpine
```

After you've deployed using [aptible deploy](/docs/reference/aptible-cli/cli-commands/cli-deploy), if you update your image or would like to deploy a different image, use [aptible deploy](/docs/reference/aptible-cli/cli-commands/cli-deploy) again (if your Docker image's name hasn't changed, you don't even need to pass the --docker-image argument again).

> 📘 If you are migrating from [deploying via Git](/docs/how-to-guides/app-guides/deploy-from-git), you should also add the --git-detach flag to this command the first time you deploy. See [Migrating from deploying via Git](/docs/how-to-guides/app-guides/migrate-dockerfile-to-direct-image-deploy) for more information.

## Deploying via Terraform

> ⚠️ Prerequisites: Install the [Aptible CLI](/docs/reference/aptible-cli/cli-commands/overview) and the Terraform CLI

### 01: Create an app

[Apps](/docs/core-concepts/apps/overview) can be created using the **terraform** **`aptible_app`** resource.

```js theme={null}
resource "aptible_app" "APP" {
    env_id = ENVIRONMENT_ID
    handle = "APP_HANDLE"
}
```

### Step 2: Deploy a Docker Image

Set your Docker image and optional registry credentials as attributes on the `aptible_app` resource:

```hcl theme={null}
resource "aptible_app" "APP" {
    env_id = ENVIRONMENT_ID
    handle = "APP_HANDLE"
    docker_image = "quay.io/aptible/deploy-demo-app"
    private_registry_username = "registry_username"
    private_registry_password = "registry_password"
    config = {
        "KEY" = "value"
    }
}
```

> 📘 Please ensure you have the correct image, username, and password set every time you run `terraform apply`. See [Terraform's refresh documentation](https://developer.hashicorp.com/terraform/cli/commands/refresh) for more information.

## Deploying via CI/CD

See related guide: [How to deploy to Aptible with CI/CD](/docs/how-to-guides/app-guides/how-to-deploy-aptible-ci-cd#deploying-with-docker)


# How to deploy from Git
Source: https://www.aptible.com/docs/how-to-guides/app-guides/deploy-from-git

Guide for deploying from Git

## **Overview**

With Aptible, you have the option to deploy your code directly from Git. This method involves pushing your source code, including a Dockerfile, to Aptible's Git repository. Aptible will then create a Docker image for you, simplifying the deployment process. This guide will walk you through the steps of deploying via Git to Aptible.

## Deploying via the Dashboard

The easiest way to deploy via Git within the Aptible Dashboard is by deploying a [template](/docs/getting-started/deploy-starter-template/overview) or [custom code](/docs/getting-started/deploy-custom-code) using the Deploy tool.

## Deploying via the CLI

> ⚠️ Prerequisites: Install the [Aptible CLI](/docs/reference/aptible-cli/cli-commands/overview)

**Step 1: Create an app**

Use the `aptible apps:create` to create an [app](/docs/core-concepts/apps/overview). Note the provided Git Remote. As we advance in this article, we'll refer to it as `$GIT_URL`.

**Step 2: Create a git repository on your local workstation**

Example:

```pl theme={null}
git init test-dockerfile-deploy
cd test-dockerfile-deploy
```

**Step 3: Add your** [**Dockerfile**](/docs/core-concepts/apps/deploying-apps/image/deploying-with-git/overview) **in the root of the repository**

Example:

```pl theme={null}
# Declare a base image:
FROM httpd:alpine

# Tell Aptible this app will be accessible over port 80:
EXPOSE 80

# Tell Aptible to run "httpd -f" to start this app:
CMD ["httpd", "-f"]
```

Step 4: Deploy to Aptible:

```pl theme={null}
# Commit the Dockerfile
git add Dockerfile
git commit -m "Add a Dockerfile"

# This URL is available in the Aptible Dashboard under "Git Remote".
# You got it after creating your app.
git remote add aptible "$GIT_URL"

# Push to Aptible
git push aptible master
```

## Deploying via Terraform

Deploying via Git is not supported by Terraform. Use [deploying via Docker image](/docs/how-to-guides/app-guides/migrate-dockerfile-to-direct-image-deploy) with Terraform instead.


# Deploy Metric Drain with Terraform
Source: https://www.aptible.com/docs/how-to-guides/app-guides/deploy-metric-drain-with-terraform



Deploying [Metric Drains](/docs/core-concepts/observability/metrics/metrics-drains/overview) with [Aptible's Terraform Provider](https://registry.terraform.io/providers/aptible/aptible/latest) is relativley straight-forward, with some minor configuration exceptions. Aptible's Terraform Provider uses the Aptible CLI for authorization and authentication, so please run `aptible login` before we get started.

## Prerequisites

1. [Terraform](https://developer.hashicorp.com/terraform/install?ajs_aid=c5fc0f0b-590f-4dee-bf72-6f6ed1017286\&product_intent=terraform)
2. The [Aptible CLI](/docs/reference/aptible-cli/cli-commands/overview)

You also need to be logged in to Aptible.

```
$ aptible login
```

## Getting Started

First, lets set up your Terraform directory to work with Aptible. Create a directory with a `main.tf` file and then run `terraform init` in the root of the directory.

Next, you will define where you want your metric drain to capture metrics. Whether this is a new environment or an exisiting one. If you are placing this in an exisiting environment you can skip this step, just make sure you have your [environment ID](https://github.com/aptible/terraform-provider-aptible/blob/master/docs/index.md#determining-the-environment-id).

```js theme={null}
data "aptible_stack" "test-stack" {
    name = "test-stack"
}

resource "aptible_environment" "test-env" {
    stack_id = data.aptible_stack.test-stack.stack_id
    // if you use a shared stack above, you will have to manually grab your org_id
    org_id = data.aptible_stack.test-stack.org_id
    handle = "test-env"
}
```

Next, we will actually create the metric drain resource in Terraform, please select the drain type you wish to use from below.

<Tabs>
  <Tab title="Datadog">
    ```js theme={null}
    resource "aptible_metric_drain" "datadog_drain" {
    env_id     = data.aptible_environment.example.env_id
    drain_type = "datadog"
    api_key    = "xxxxx-xxxxx-xxxxx"
    }
    ```
  </Tab>

  <Tab title="Aptible InfluxDB Database">
    ```js theme={null}
    resource "aptible_metric_drain" "influxdb_database_drain" {
    env_id      = data.aptible_environment.example.env_id
    database_id = aptible_database.example.database_id
    drain_type  = "influxdb_database"
    handle      = "aptible-hosted-metric-drain"
    }
    ```
  </Tab>

  <Tab title="InfluxDB">
    ```js theme={null}
    resource "aptible_metric_drain" "influxdb_drain" {
    env_id     = data.aptible_environment.example.env_id
    drain_type = "influxdb"
    handle     = "influxdb-metric-drain"
    url        = "https://influx.example.com:443"
    username   = "example_user"
    password   = "example_password"
    database   = "metrics"
    }
    ```
  </Tab>
</Tabs>

To check to make sure your changes are valid (in case of any changes not mentioned), run `terraform validate`

To deploy the above changes, run `terraform apply`

## Troubleshooting

## App configuration issues with Datadog

> Some users have reported issues with applications not sending logs to Datadog, applications will need additional configuration set. Below is an example.

```js theme={null}
    resource "aptible_app" "load-test-datadog" {
        env_id = data.aptible_environment.example_environment.env_id
        handle = "example-app"
        docker_image = "docker.io/datadog/agent:latest"
        config = {
            "DD_APM_NON_LOCAL_TRAFFIC" : true,
            "DD_BIND_HOST" : "0.0.0.0",
            "DD_API_KEY" :"xxxxx-xxxxx-xxxxx",
            "DD_HOSTNAME_TRUST_UTS_NAMESPACE" : true,
            "DD_ENV" : "your environment",
            "DD_HOSTNAME" : "dd-hostname" # this does not have to match the hostname
        }
        service {
            process_type = "cmd"
            container_count = 1
            container_memory_limit = 1024
        }
    }
```

As a final note, if you have any questions about the Terraform provider please reach out to support or checkout our public [Terraform Provider Repository](https://github.com/aptible/terraform-provider-aptible) for more information!


# How to deploy a preview app to Aptible using Github Actions
Source: https://www.aptible.com/docs/how-to-guides/app-guides/deploy-preview-app



## Overview

This guide offers step-by-step instructions for implementing and customizing GitHub workflows to deploy preview apps on the Aptible platform. The workflows described in this documentation are included in this [example repository](https://github.com/aptible/deploy-demo-preview-example/tree/main/.github/workflows), are ready for production, and can be adapted to suit your specific deployment requirements and integration needs.

### Preview Deployment (preview\.yml)

The preview\.yml workflow automatically deploys a preview app for every pull request, enabling reviewers to test the changes introduced in the PR in a separate app in a selected Aptible environment.

**What this workflow does:**

1. Triggers automatically when pull requests are created or updated with new commits
2. Creates a PostgreSQL database and a Redis database for the preview app
3. Configures a new Aptible app configured with the necessary environment variables to connect to the databases from the previous step
4. Builds and pushes a Docker image tagged with the PR number
5. Deploys the application to Aptible using the image built in the previous step
6. Creates an HTTPS endpoint for accessing the preview app

### Preview Cleanup (deprovision\_preview\.yml)

The `deprovision_preview.yml` workflow handles the cleanup of preview resources when a pull request is closed.

**What this workflow does:**

1. Triggers when a pull request is closed (merged or rejected).
2. Deprovisions the Aptible app and endpoint associated with the PR.
3. Deprovisions the PostgreSQL and Redis databases created for the preview.

### Prerequisites

To deploy to Aptible via Git, you must have a public SSH key associated with your account. We recommend creating a robot user to manage your deployment:

1. Create a "Robots" [custom role](/docs/core-concepts/security-compliance/access-permissions) in your Aptible [organization](/docs/core-concepts/security-compliance/access-permissions), and grant it "Full Visibility" and "Deployment" [permissions](/docs/core-concepts/security-compliance/access-permissions) for the [environment](/docs/core-concepts/architecture/environments) where you will be deploying.
2. Invite a new robot user with a valid email address (for example, `deploy@yourdomain.com`) to the `Robots` role.
3. Sign out of your Aptible account, accept the invitation from the robot user's email address, and set a password for the robot's Aptible account.
4. Generate a new SSH key pair to be used by the robot user, and don't set a password: `ssh-keygen -t ed25519 -C "your_email@example.com"`
5. Register the [SSH Public Key](/docs/core-concepts/security-compliance/authentication/ssh-keys) with Aptible for the robot user.

### Configuring the Environment

Add the following [secrets](https://docs.github.com/en/actions/security-guides/encrypted-secrets#using-encrypted-secrets-in-a-workflow) in Github:

* APTIBLE\_ROBOT\_PASSWORD: Password for your Aptible robot account
* DOCKERHUB\_USERNAME: Your Docker Hub username
* DOCKERHUB\_TOKEN: Access token for Docker Hub
* DOCKERHUB\_PASSWORD: Your Docker Hub password

Add the following [variable](https://docs.github.com/en/actions/how-tos/writing-workflows/choosing-what-your-workflow-does/store-information-in-variables) in Github

* APTIBLE\_ROBOT\_USERNAME: Email address of your Aptible robot account

### Update the workflows and add them to your repository

1. Update the environment variables:
   1. Replace `preview-apps` with your Aptible environment name.
   2. Replace `aptible/deploy-demo-app` with your Docker image name.
   3. Adjust the app name pattern if needed.
2. Modify the database type, version, and name pattern as needed for your application.
3. Update the tagging strategy if required in the `Build and Push Docker images` step.
4. You can customize the workflow further by using different [<u>event types to trigger</u>](https://docs.github.com/en/actions/reference/events-that-trigger-workflows) the workflows. The [<u>push</u>](https://docs.github.com/en/actions/reference/events-that-trigger-workflows#push) and [<u>pull\_request</u>](https://docs.github.com/en/actions/reference/events-that-trigger-workflows#pull_request) event documentation, in particular, includes practical examples for everyday use cases.


# How to migrate from deploying via Docker Image to deploying via Git
Source: https://www.aptible.com/docs/how-to-guides/app-guides/deploying-docker-image-to-git

Guide for migrating from deploying via Docker Image to deploying via Git

## Overview

Suppose you configured your app to [deploy via Docker Image](/docs/how-to-guides/app-guides/migrate-dockerfile-to-direct-image-deploy), i.e., you deployed using [`aptible deploy`](/docs/reference/aptible-cli/cli-commands/cli-deploy) in the past, and you want to switch to [deploying via Git](/docs/how-to-guides/app-guides/deploy-from-git) instead. In that case, you will need to take the following steps:

**Step 1:** Push your git repository to a temporary branch. This action will not trigger a deploy, but we'll use it in just a moment:

```perl theme={null}
BRANCH="deploy-$(date "+%s")"
git push aptible "master:$BRANCH"
```

**Step 2:** Deploy the temporary branch (using the `--git-commitish` argument), and use an empty string for the `--docker-image` argument to disable deploying via Docker Image.

```perl theme={null}
aptible deploy --app "$APP_HANDLE" \
        --git-commitish "$BRANCH" \
        --docker-image ""
```

**Step 3:** Use `git push aptible master` for all deploys moving forward.

Please note if your [app](/docs/core-concepts/apps/overview) has [Private Registry Credentials](/docs/core-concepts/apps/overview), Aptible will attempt to log in using these credentials. Unless the app uses a private base image in its Dockerfile, these credentials should not be necessary. To prevent private registry authentication, unset the credentials when deploying:

```perl theme={null}
aptible deploy --app "$APP_HANDLE" \
        --git-commitish "$BRANCH" \
        --docker-image "" \
        --private-registry-username "" \
        --private-registry-password ""
```

Congratulations! You are now set to deploy via Git.


# How to establish client certificate authentication
Source: https://www.aptible.com/docs/how-to-guides/app-guides/establish-client-certificiate-auth

Client certificate authentication, also known as two-way SSL authentication, is a form of mutual Transport Layer Security(TLS) authentication that involves both the server and the client in the authentication process. Users and the third party they are working with need to establish, own, and manage this type of authentication.

<Warning>
  **Industry changes affecting client certificate authentication**

  Publicly trusted Certificate Authorities (CAs) are narrowing the scope of standard TLS certificates, and client authentication is being deprecated or removed from typical public CA issuance. If you need durable mutual TLS (mTLS) for client certificate authentication, you should plan for private PKI for client certificates.

  For background on the broader ecosystem changes, see [Let's Encrypt's announcement](https://letsencrypt.org/2025/05/14/ending-tls-client-authentication).
</Warning>

## Standard TLS Authentication v. Mutual TLS Authentication

The standard TLS authentication process works as follows:

1. The client sends a request to the server.

2. The server presents its SSL certificate to the client.

3. The client validates the server's SSL certificate with the certificate authority that issued the server's certificate. If the certificate is valid, the client generates a random encryption key, encrypts it with the server's public key, and then sends it to the server.

4. The server decrypts the encryption key using its private key. The server and client now share a secret encryption key and can communicate securely.

Mutual TLS authentication includes additional steps:

1. The server will request the client's certificate.

2. The client sends its certificate to the server.

3. The server validates the client's certificate with the certificate authority that issued it. If the certificate is valid, the server can trust that the client is who it claims to be.

## Generating a Client Certificate

Client certificate authentication is more secure than using an API key or basic authentication because it verifies the identity of both parties involved in the communication and provides a secure method of communication. However, setting up and managing client certificate authentication is also more complex because certificates must be generated, distributed, and validated for each client. A client certificate is typically a digital certificate used to authenticate requests to a remote server.

For example, if you are working with a third-party API, their server can ensure that only trusted clients can access their API by requiring client certificates. The client in this example would be your application sending the API request. We recommend that you verify accepted Certificate Authorities with your third-party API provider and then generate a client certificate using these steps:

1. Generate a private key. This must be securely stored and should never be exposed or transmitted. It's used to generate the Certificate Signing Request (CSR) and to decrypt incoming messages.

2. Use the private key to generate a Certificate Signing Request (CSR). The CSR includes details like your organization's name, domain name, locality, and country.

3. Submit this CSR to a trusted Certificate Authority (CA). The CA verifies the information in the CSR to ensure that it's accurate. After verification, the CA will issue a client certificate, which is then sent back to you.

4. Configure your application or client to use both the private key and the client certificate when making requests to the third-party service.

> 📘 Certificates are only valid for a certain time (like one or two years), after which they need to be renewed. Repeat the process above to get a new certificate when the old one expires.

## Recommended approach: Private PKI for client certificates

For durable mutual TLS client certificate authentication, we recommend using a private PKI (Public Key Infrastructure) solution. Private PKI provides several advantages over public CAs for client certificates:

* **Control over issuance**: You control certificate issuance policies, validation requirements, and certificate lifetimes
* **Rotation and short lifetimes**: Enable automated certificate rotation with shorter validity periods for improved security
* **Revocation**: Manage certificate revocation lists (CRLs) or use Online Certificate Status Protocol (OCSP) for your infrastructure
* **Distributing trust**: You control which root and intermediate certificates are trusted by your clients and servers

Private PKI can be deployed in several ways:

* **Internal CA**: Run your own certificate authority infrastructure
* **Hosted PKI**: Use a hosted PKI service that manages the CA infrastructure for you
* **Managed private CA**: Use a cloud provider's managed private certificate authority service

### Example solutions

* **[Smallstep step-ca](https://smallstep.com/docs/step-ca/)**: An open-source private CA with ACME support for automation, suitable for both internal and hosted deployments
* **[AWS Private Certificate Authority](https://docs.aws.amazon.com/privateca/latest/userguide/PcaWelcome.html)**: A managed private CA service that integrates with AWS services and supports automated certificate lifecycle management

### Trust model considerations

Unlike public TLS certificates that work everywhere by default, mTLS with private PKI requires you to control which root and intermediate certificates are trusted by your clients and servers. You must distribute your CA's root certificate (or intermediate certificates) to all parties that need to validate client certificates. This gives you full control over your trust model but requires explicit trust distribution.

## Commercial Certificate Authorities (CAs)

Some commercial CAs may have historically issued client certificates for use in client certificate authentication. However, availability and policies vary by provider and are changing as the industry shifts away from public CA-issued client certificates.

<Warning>
  **Verify current availability**: Before relying on a commercial CA for client certificates, verify that the CA still offers client-auth certificates for your specific use case and trust model. Expect this to become harder with public trust stores over time, and plan accordingly for long-term mTLS deployments.
</Warning>

The following CAs have historically offered client certificate services, but availability and policies may have changed:

1. DigiCert: one of the most popular providers of SSL/TLS certificates and can also issue client certificates.

2. GlobalSign: offers PersonalSign certificates that can be used for client authentication.

3. Sectigo (formerly Comodo): provides several client certificates, including the Sectigo Personal Authentication Certificate.

4. Entrust Datacard: offers various certificate services, including client certificates.

5. GoDaddy: known primarily for its domain registration services but also offers SSL certificates, including client certificates.

**Note**: For transitional or short-term use cases, a commercial public CA might still be acceptable, but private PKI is the recommended path for production mTLS deployments.


# How to expose a web app to the Internet
Source: https://www.aptible.com/docs/how-to-guides/app-guides/expose-web-app-to-internet



This guide assumes you already have a web app running on Aptible. If you don't have one already, you can create one using one of our [Quickstart Guides](/docs/getting-started/deploy-starter-template/overview).

This guide will walk you through the process of setting up an [HTTP(S) endpoint](/docs/core-concepts/apps/connecting-to-apps/app-endpoints/https-endpoints/overview) with [external placement](/docs/core-concepts/apps/connecting-to-apps/app-endpoints/overview#endpoint-placement) using a [custom domain](/docs/core-concepts/apps/connecting-to-apps/app-endpoints/custom-domain) and [managed TLS](/docs/core-concepts/apps/connecting-to-apps/app-endpoints/managed-tls).

Let's unpack this sentence:

* [HTTP(S) Endpoint](/docs/core-concepts/apps/connecting-to-apps/app-endpoints/https-endpoints/overview): the endpoint will accept HTTPS and HTTP traffic. Aptible will handle HTTPS termination for you, so your app simply needs to process HTTP requests.

* [External Placement](/docs/core-concepts/apps/connecting-to-apps/app-endpoints/overview#endpoint-placement): the endpoint will be reachable from the public internet.

* [Custom Domain](/docs/core-concepts/apps/connecting-to-apps/app-endpoints/custom-domain): the endpoint will use a domain you provide(e.g. `www.example.com`).

* [Managed TLS](/docs/core-concepts/apps/connecting-to-apps/app-endpoints/managed-tls): Aptible will provision an SSL / TLS certificate on your behalf.

Learn more about other choices here: [Endpoints](/docs/core-concepts/apps/connecting-to-apps/app-endpoints/overview). Let's move on to the process.

## Create the endpoint

In the Aptible Dashboard:

* Navigate to your app

* Navigate to the Endpoints tab

* Create a new endpoint

  * Update the following settings and leave the rest as default:

    * **Type**: Custom Domain with Managed HTTPS.

    * **Endpoint Placement**: External.

    * **Domain Name**: the domain name you intend to use. In the example above, that was `www.example.com`, but yours will be different.

* Save and wait for the endpoint to provision. If provisioning fails, jump to [Endpoint Provisioning Failed](/docs/how-to-guides/app-guides/expose-web-app-to-internet#endpoint-provisioning-failed).

> 📘 The domain name you choose should **not** be a domain apex. For example, [www.example.com](http://www.example.com/) is fine, but just example.com is not.

> For more information, see: [How do I use my domain apex with Aptible?](/docs/how-to-guides/app-guides/use-domain-apex-with-endpoints/overview)

## Create a CNAME to the endpoint

Aptible will present you with an [endpoint hostname](/docs/core-concepts/apps/connecting-to-apps/app-endpoints/custom-domain#endpoint-hostname) and [managed HTTPS validation records](/docs/core-concepts/apps/connecting-to-apps/app-endpoints/managed-tls#managed-https-validation-records) once the endpoint provisions. The two have different but overlapping use cases.

### Endpoint hostname

The Endpoint Hostname is a domain name that points to your endpoint.

However, you shouldn't send your traffic directly there. Instead, you should create a CNAME DNS record (using your DNS provider) from the name you intend to use with your app (`www.example.com` in the example above) to the Endpoint Hostname.

So, create that CNAME now.

### Validation records

Managed TLS uses the validation records to provision a certificate for your domain via [Let's Encrypt](https://letsencrypt.org/). When you create those records, Aptible can provide certificates for you. If you don't create them, then Let's Encrypt won't let Aptible provision certificates for you.

As it happens, the CNAME you created for the Endpoint Hostname is *also* a validation record. That makes sense: you're sending your traffic to the endpoint; that's enough proof for Let's Encrypt that you're indeed using Aptible and that we should be able to create certificates for you. Note that there are two validation records. We recommend you create both, but you're not going to need the second one (the one starting with `_acme-challenge`) for this tutorial.

## Validate the endpoint

Confirm that you've created the CNAME from your domain name to the Endpoint Hostname in the Dashboard. Aptible will provision a certificate for you, then deploy it across your app.

If all goes well, you'll see a success message (if not, see [Endpoint Certificate Renewal Failed](/docs/how-to-guides/app-guides/expose-web-app-to-internet#endpoint-certificate-renewal-failed) below).

You can navigate to your custom domain (over HTTP or HTTPS), and your app will be accessible.

## Next steps

Now that your app is available over HTTPS, enabling an automated [HTTPS Redirect](/docs/core-concepts/apps/connecting-to-apps/app-endpoints/https-endpoints/https-redirect) is a good idea.

You can also learn more about endpoints here: [Endpoints](/docs/core-concepts/apps/connecting-to-apps/app-endpoints/overview).

## Troubleshooting

### Endpoint Provisioning Failed

If endpoint provisioning fails, restart your app using the [`aptible restart`](/docs/reference/aptible-cli/cli-commands/cli-restart) command. You will see a prompt asking you to do so.

Note this failure is most likely due to an app health check failure. We have troubleshooting instructions here: [My deploy failed with *HTTP health checks failed*](/docs/how-to-guides/troubleshooting/common-errors-issues/http-health-check-failed).

If this doesn't help, contact [Aptible Support](/docs/how-to-guides/troubleshooting/aptible-support).

### Endpoint Certificate Renewal Failed

This failure is probably due to an issue with the CNAME you created. There are two possible causes here:

* The CNAME change is taking a little to propagate. Here, it's a good idea to wait for a few minutes (or seconds, if you're in a hurry!) and then retry via the Dashboard.

* The CNAME is wrong. An excellent way to check for this is to access your domain name (`www.example.com` in the examples above, but yours will be different). If you see an Aptible page saying something like "you're almost done", you probably got it right, and you can retry via the Dashboard. If not, double-check the CNAME you created.

If this doesn't help, contact [Aptible Support](/docs/how-to-guides/troubleshooting/aptible-support).


# How to generate certificate signing requests
Source: https://www.aptible.com/docs/how-to-guides/app-guides/generate-certificate-signing-requests



> 📘 If you're unsure about creating certificates or don't want to manage them, use Aptible's [Managed TLS](/docs/core-concepts/apps/connecting-to-apps/app-endpoints/managed-tls) option!

A [Certificate Signing Request](https://en.wikipedia.org/wiki/Certificate_signing_request) (CSR) file contains information about an SSL / TLS certificate you'd like a Certification Authority (CA) to issue. If you'd like to use a [Custom Certificate](/docs/core-concepts/apps/connecting-to-apps/app-endpoints/custom-certificate) with your [Endpoints](/docs/core-concepts/apps/connecting-to-apps/app-endpoints/overview), you will need to generate a CSR:

**Step 1:** You can generate a new CSR using OpenSSL's `openssl req` command:

```bash theme={null}
openssl req -newkey rsa:2048 -nodes \
        -keyout "$DOMAIN.key" -out "$DOMAIN.csr"
```

**Step 2:** Store the private key (the `$DOMAIN.key` file) and CSR (the `$DOMAIN.csr` file) in a secure location, then request a certificate from the CA of your choice.

**Step 3:** Once your CSR is approved, request an "NGiNX / other" format if the CA asks what certificate format you prefer.

## Matching Certificates, Private Keys and CSRs

If you are unsure which certificates, private keys, and CSRs match each other, you can compare the hashes of the modulus of each:

```bash theme={null}
openssl x509 -noout -modulus -in certificate.crt | openssl md5
openssl rsa -noout -modulus -in "$DOMAIN.key" | openssl md5
openssl req -noout -modulus -in "$DOMAIN.csr" | openssl md5
```

The certificate, private key and CSR are compatible if all three hashes match. You can use `diff3` to compare the moduli from all three files at once:

```bash theme={null}
openssl x509 -noout -modulus -in certificate.crt > certificate-mod.txt
openssl rsa -noout -modulus -in "$DOMAIN.key" > private-key-mod.txt
openssl req -noout -modulus -in "$DOMAIN.csr" > csr-mod.txt
diff3 cert-mod.txt privkey-mod.txt csr-mod.txt
```

If all three files are identical, `diff3` will produce no output.

> 📘 You can reuse a private key and CSR when renewing an SSL / TLS certificate, but from a security perspective, it's often a better idea to generate a new key and CSR when renewing.


# Getting Started with Docker
Source: https://www.aptible.com/docs/how-to-guides/app-guides/getting-started-with-docker



On Aptible, we offer two application deployment strategies - [deploying via Git](/docs/how-to-guides/app-guides/deploy-from-git) and [deploying via Docker image](/docs/how-to-guides/app-guides/migrate-dockerfile-to-direct-image-deploy). You’ll notice that both options involve Docker, a popular container runtime platform. Aptible uses Docker to help deploy your applications in containers, allowing you to easily scale, manage, and deploy applications in isolation. In this guide, we’ll review the basics of using Docker to deploy on Aptible.

## Writing a Dockerfile

For both deployment options offered on Aptible, you’ll need to know how to write a Dockerfile. A Dockerfile contains all the instructions to describe how a Docker Image should be built. Docker has a great guide on [Dockerfile Best Practices](https://docs.docker.com/develop/develop-images/dockerfile_best-practices/), which we recommend checking out before starting. You can also use the Dockerfiles included in our [Starter Templates](/docs/getting-started/deploy-starter-template/overview) as a reference to kickstart your own. Below is an example taken from our [Ruby on Rails Starter Template](/docs/getting-started/deploy-starter-template/ruby-on-rails):

```ruby theme={null}
# syntax = docker / dockerfile: 1

#[1] Choose a parent image to base your image on
FROM ruby: latest

#[2] Do things that are necessary for your Application to run
RUN apt - get update \
 && apt - get - y install build - essential libpq - dev \
 && rm - rf /var/lib/apt / lists/*

ADD Gemfile /app/
ADD Gemfile.lock /app/
WORKDIR /app
RUN bundle install

ADD . /app

EXPOSE 3000

# [3] Configure the default process to run when running the container
CMD ["bundle", "exec", "rails", "server", "-b", "0.0.0.0", "-p", "3000"]
```

You can typically break down a basic Dockerfile into three main sections - we’ve marked them as \[1], \[2], and \[3] in the example.

1. Choose a parent image:

   * This is the starting point for most users. A parent image provides a foundation for your own image - every subsequent line in your Dockerfile modifies the parent image.

   * You can find parent images to use from container registries like [Docker Hub](https://hub.docker.com/search?q=\&type=image).

2. Build your image

   * The instructions in this section help build your image. In the example, we use `RUN`, which executes and commits a command before moving on to the next instruction, `ADD`, which adds a file or directory from your source to a destination, `WORKDIR`, which changes the working directory for subsequent instructions, and `EXPOSE`, which instructs the container to listen on the specified port at runtime.

   * You can find detailed information for each instruction on Docker’s Dockerfile reference page.

3. Configure the default container process

   * The CMD instruction provides defaults for running a container.

   * We’ve included the executable command bundle in the example, but you don’t necessarily need to. If you don’t include an executable command, you must provide an `ENTRYPOINT` instead.

> 📘 On Aptible, you can optionally include a [Procfile](/docs/how-to-guides/app-guides/define-services) in the root directory to define explicit services. How we interpret the commands in your Procfile depends on whether or not you have an ENTRYPOINT defined.

Lint Dockerfiles in CI before you build, then scan built images before you deploy. See [Image and Vulnerability Scanning](/docs/how-to-guides/platform-guides/image-vulnerability-scanning).

## Building a Docker Image

A Docker image is the packaged version of your application - it contains the instructions necessary to build a container on the Docker platform. Once you have a Dockerfile, you can have Aptible build and deploy your image via [deploying via Git](/docs/how-to-guides/app-guides/deploy-from-git) or build it yourself and provide us the Docker Image via [deploying via Docker image](/docs/how-to-guides/app-guides/migrate-dockerfile-to-direct-image-deploy).

The steps below, which require the [Aptible CLI](/docs/reference/aptible-cli/cli-commands/overview) and [Docker CLI](https://docs.docker.com/get-docker/), provide a general outline on building and deploying a Docker image to Aptible.

1. docker build with your Dockerfile and context to build your image.

2. docker push to push your image to a container registry, like Docker Hub.

3. `aptible deploy --docker-image “$DOCKER_IMAGE” --app “$APP”` to deploy your image to an App on Aptible


# Horizontal Autoscaling Guide
Source: https://www.aptible.com/docs/how-to-guides/app-guides/horizontal-autoscaling-guide



<Note>This feature is is only available on the [Production and Enterprise plans.](https://www.aptible.com/pricing)</Note>

[Horizontal Autoscaling (HAS)](/docs/core-concepts/scaling/app-scaling#horizontal-autoscaling) is a powerful feature that allows your application to automatically adjust its computing resources based on ongoing usage. This guide will walk you through the benefits, ideal use cases, and best practices for implementing HAS in your Aptible deployments.

By leveraging HAS, you can optimize resource utilization, improve application performance, and potentially reduce costs. Whether you're running a web service, API, or any other scalable application, understanding and properly configuring HAS can significantly enhance your infrastructure's efficiency and reliability.

Let's dive into the key aspects of Horizontal Autoscaling and how you can make the most of this feature for your Aptible-hosted applications.

# Key Benefits of Horizontal Autoscaling

* Cost efficiency & Performance: Ensure your App Services are always using the optimal amount of containers. Scale loads with periods of high and low usage that can be parallelized - efficiently.
* Greater reliability: Reduce the likelihood of an expensive computation (ie. a web request) consuming all of your fixed size processing capability
* Reduced engineering time: Save time manually scaling your app services with greater automation

# What App Services are good candidates for HAS?

**First, let’s consider what sort of process is NOT a candidate:**

* Job workers, unless your jobs are idempotent and/or your queue follows exactly-once semantics
* Services that cannot be easily parallelized
  * If your workload is not easily parallelized, you could end up in a scenario where all the load is on one container and the others do near-zero work.

### So what’s a good candidate?

* Services that have predictable and well-understood load patterns
  * We talk about this more in [How to determine the right Horizontal Autoscaling configuration for your App Services](#how-to-determine-the-right-horizontal-autoscaling-configuration-for-your-app-services)
* Services that have a workload that can be easily parallelized
  * Web workers as an example, since each web request is completely independent from another
* Services that experience periods of high/low load
  * However, there’s no real risk to setting up HAS on any service just in case they ever experience higher load than expected, as long as having multiple processes running at the same time is not a problem (see above for processed that are not candidates).

# How to determine the right Horizontal Autoscaling configuration for your App Services

Horizontal Autoscaling is configured per App Service. Guidelines to keep in mind for configuration:

* Minimum number of containers - Should be set to 2 as a minimum if you want High-Availability
* Max number of containers - This one depends on how many requests you want to be able to handle under load, and will differ due to specifics of how your app behaves. If you’ve done load testing with your app and understand how many requests your app can handle with the container size you’re currently using, it is a matter of calculating how many more containers you’d want.
* Min CPU threshold - You should set this to slightly above the CPU usage your app exhibits when there’s no/minimal usage to ensure scale downs happen, any lower and your app will never scale down. If you want scale downs to happen faster, you can set this threshold higher.
* Max CPU threshold - A good rule of thumb is 80-90%. There is some lead time to scale ups occurring, as we need a minimum amount of metrics to have been gathered before the next scale-up event happens, so setting this close to 100% can lead to bottlenecks. If you want scale ups to happen faster, you can set this threshold lower.
* Scale Up, and Scale Down Steps - These are set to 1 by default, but you are able to modify the values if you want autoscaling events to jump up or down by more than 1 container at a time.

<Tip>CPU thresholds are expressed as a decimal between 0 and 1, representing the percentage of your container's allocated CPU that is actively used by your app. For instance, if a container with a 25% CPU limit is using 12% of its allocated CPU, this would be expressed as 0.48 (or 48%).</Tip>

## Percentile + Scale Up / Down Thresholds (CPU Usage)

Percentiles decide how aggressively the autoscaler reacts to spikes in CPU usage. For example:

* **P90:** Ignores the top 10% of CPU spikes. This ensures that application performance is mostly within the desired range by focusing on general performance trends.
* **P95:** Ignores the top 5% of CPU spikes. This ensures better overall performance, but will also result in more scaling activity.
* **P99:** Ignores the top 1% of CPU spikes. This results in the most scaling activity, but also the best performance.

Below is an example of what P90, P95, and P99 might look like for the same exact application Scale Up Threshold of 80%.

<img alt="" />

<img alt="" />

<img alt="" />

## Scale Up/Down Cooldowns

Cooldowns add deliberate pauses between scaling events to give your app time to stabilize and to prevent rapid repeated scaling events.

In the example below, we wouldn’t scale up during the Scale Up Cooldown, even though CPU usage remains consistently over the Scale Up Threshold of 80%.

<img alt="" />

## Post Release Cooldown

After a deployment, Aptible discards metrics within this interval to allow for service stabilization.

In the example below, we would not scale up even though usage is over the 80% Scale Up Threshold for
most of the Metric Lookback Time Interval. This is because the data within the Post Release Cooldown window is not included when evaluating whether or not to autoscale.

<img alt="" />

### Let’s go through an example:

We have a service that exhibits periods of load and periods of near-zero use. It is a production service that is critical to us, so we want a high-availability setup, which means our minimum containers will be 2. Metrics for this service are as follows:

| Container Size | CPU Limit | Low Load CPU Usage     | High Load CPU Usage     |
| -------------- | --------- | ---------------------- | ----------------------- |
| 1GB            | 25%       | 3% (12% of allocation) | 22% (84% of allocation) |

Since our low usage is 12%, the HAS default of 0.1 won’t work for us - we would never scale down. Let’s set it to 0.2 to be conservative

At 84% usage when under load, we’re near the limit but not quite topped out. Usually this would mean you need to validate whether this service would actually benefit from having more containers running. In this case, let’s say our monitoring tools have surfaced that request queueing gets high during these times. We could set our scale up threshold to 0.8, the default, or set it a bit lower if we want to be conservative.

With this, we can expect our service to scale up during periods of high load, up to the maximum number of containers if necessary. If we had set our max CPU limit to something like 0.9, the scaling up would be unlikely to trigger *in this particular scenario.* We may want to also consider enabling [Restart Free Scaling](/docs/core-concepts/scaling/app-scaling#horizontal-autoscaling) to avoid the additional overhead of restarting all containers when scaling up during times of already high load.

With the metrics look-back period set to 10 minutes and our scale-up cooldown set to a minute(the default), we can expect our service to scale up by 1 container every 5 minutes as long as our load across all containers stays above 80%, until we reach the maximum containers we set in the configuration. Note the 5 minutes between each event - that is currently a hardcoded minimum cooldown.

Since we set a min CPU (scale down) threshold high enough to be above our containers minimal usage, we have guaranteed scale downs will occur. We could set our scale-down threshold higher if we want to be more aggressive about maximizing container utility.

### Autoscaling Worker/Job processes

You can use horizontal autoscaling to scale your worker/job processes. However, you should consider some additional configurations:

* **Restart Free Scaling**: When enabled, scale operations for modifying the number of running containers will not restart the other containers in the service. This is particularly useful for worker/job processes, as it allows you to scale up without interrupting work on the containers already processing jobs.
* **Service Stop Timeout**: When scaling down, the service stop timeout is respected. This is particularly useful for worker/job processes, since it allows time to either finish processing the current job, or put the job back on the queue for processing by another container. Note that containers are selected for removal based on the [`APTIBLE_PROCESS_INDEX` metadata variable](/docs/reference/aptible-metadata-variables), selecting higher indices first, so if possible you should prefer to process long running jobs on containers with a lower index.


# How to create an app
Source: https://www.aptible.com/docs/how-to-guides/app-guides/how-to-create-app



Learn how to create an [app](/docs/core-concepts/apps/overview)

> ❗️Apps handles cannot start with "internal-" because applications with that prefix cannot have [Endpoints](/docs/core-concepts/apps/connecting-to-apps/app-endpoints/overview)

## Using the Dashboard

Apps can be created/provisioned within the Dashboard the following ways:

* Using the [**Deploy**](https://app.aptible.com/create) tool will automatically create a new app in a new environment as you deploy your code <img alt="" />

* From the Environment by:

  * Navigating to the respective Environment

  * Selecting the **Apps** tab

  * Selecting **Create App**

<img alt="" />

## Using the CLI

Apps can be created/provsioned via the Aptible CLI by using the [`aptible apps:create`](/docs/reference/aptible-cli/cli-commands/cli-apps-create) command.

```js theme={null}
aptible apps:create HANDLE
```

## Using Terraform

Apps can be created/provsioned via the [Aptible Terraform Provider](https://registry.terraform.io/providers/aptible/aptible/latest/docs) by using the terraform\_aptible\_app resource.

```js theme={null}
data "aptible_app" "APP" {
    handle = "APP_HANDLE"
}
```


# How to deploy to Aptible with CI/CD
Source: https://www.aptible.com/docs/how-to-guides/app-guides/how-to-deploy-aptible-ci-cd



## Overview

To make it easier to deploy on Aptible—whether you're migrating from another platform or deploying your first application—we offer integrations with several continuous integration services.

* [Deploying with Git](/docs/how-to-guides/app-guides/how-to-deploy-aptible-ci-cd#deploying-with-git)

* [Deploying with Docker](/docs/how-to-guides/app-guides/how-to-deploy-aptible-ci-cd#deploying-with-docker)

If your team is already using a Git-based deployment workflow, deploying your app to Aptible should be relatively straightforward.

Before you deploy, lint Dockerfiles and scan built images in CI so vulnerable or misconfigured images never reach production. See [Image and Vulnerability Scanning](/docs/how-to-guides/platform-guides/image-vulnerability-scanning).

## Deploying with Git

### Prerequisites

To deploy to Aptible via Git, you must have a public SSH key associated with your account. We recommend creating a robot user to manage your deployment:

1. Create a "Robots" [custom role](/docs/core-concepts/security-compliance/access-permissions) in your Aptible [organization](/docs/core-concepts/security-compliance/access-permissions), and grant it "Full Visibility" and "Deployment" [permissions](/docs/core-concepts/security-compliance/access-permissions) for the [environment](/docs/core-concepts/architecture/environments) where you will be deploying.

2. Invite a new robot user with a valid email address (for example, `deploy@yourdomain.com`) to the `Robots` role.

3. Sign out of your Aptible account, accept the invitation from the robot user's email address, and set a password for the robot's Aptible account.

4. Generate a new SSH key pair to be used by the robot user, and don't set a password: `ssh-keygen -t ed25519 -C "your_email@example.com"`

5. Register the [SSH Public Key](/docs/core-concepts/security-compliance/authentication/ssh-keys) with Aptible for the robot user.

<Tabs>
  <Tab title="GitHub Actions">
    ### Configuring the Environment

    First, you'll need to configure a few [environment variables](https://docs.github.com/en/actions/learn-github-actions/variables#defining-configuration-variables-for-multiple-workflows) and [secrets](https://docs.github.com/en/actions/security-guides/encrypted-secrets#using-encrypted-secrets-in-a-workflow) for your repository:

    1. Environment variable: `APTIBLE_APP`, the name of the App to deploy.
    2. Environment variable: `APTIBLE_ENVIRONMENT`, the name of the Aptible environment in which your App lives.
    3. Secret: `APTIBLE_USERNAME`, the username of the Aptible user with which to deploy the App.
    4. Secret: `APTIBLE_PASSWORD`, the password of the Aptible user with which to deploy the App.

    ### Configuring the Workflow

    Finally, you must configure the workflow to deploy your application to Aptible:

    ```sql theme={null}
    on:
      push:
        branches: [ main ]

    jobs:
      deploy:
        runs-on: ubuntu-latest
        steps:
          - uses: actions/checkout@v4
            with:
              fetch-depth: 0
          - name: Deploy to Aptible
            uses: aptible/aptible-deploy-action@v5
            with:
              type: git
              app: ${{ vars.APTIBLE_APP }}
              environment: ${{ vars.APTIBLE_ENVIRONMENT }}
              username: ${{ secrets.APTIBLE_USERNAME }}
              password: ${{ secrets.APTIBLE_PASSWORD }}
    ```
  </Tab>

  <Tab title="CircleCI">
    ### Configuring SSH

    To deploy to Aptible via CircleCI, [add your SSH Private Key via the CircleCI Dashboard](https://circleci.com/docs/2.0/add-ssh-key/#circleci-cloud-or-server-3-x) with the following values:

    * **Hostname:** `beta.aptible.com`
    * **Private Key:** The contents of the SSH Private Key created in the previous step.

    ### Configuring the Environment

    You also need to set environment variables on your project with the name of your Aptible environment and app, in `APTIBLE_ENVIRONMENT` and `APTIBLE_APP`, respectively. You can add these to your project using [environment variables](https://circleci.com/docs/2.0/env-vars/) on the Circle CI dashboard.

    ### Configuring the Deployment

    Finally, you must configure the Circle CI project to deploy your application to Aptible:

    ```sql theme={null}
    version: 2.1

    jobs:
      git-deploy:
        docker:
          - image: debian:latest
        filters:
          branches:
            only:
              - circle-deploy
        steps:
          # Add your private key to your repo: https://circleci.com/docs/2.0/configuration-reference/#add-ssh-keys
          - checkout
          - run:
              name: Git push and deploy to Aptible
              command: |
                apt-get update && apt-get install -y git openssh-client
                ssh-keyscan beta.aptible.com >> ~/.ssh/known_hosts
                git remote add aptible git@beta.aptible.com:$APTIBLE_ENVIRONMENT/$APTIBLE_APP.git
                git push aptible $CIRCLE_SHA1:master

    workflows:
      version: 2
      deploy:
        jobs:
          - git-deploy
    ```

    Let’s break down how this works. We begin by defining when the deployment should run (when a push is made to the `circle-deploy` branch):

    ```sql theme={null}
    jobs:
      git-deploy:
        docker:
          - image: debian:latest
        filters:
          branches:
            only:
              - circle-deploy
    ```

    The most important part of this configuration is the value of the `command` key under the `run` step. Here we add our SSH private key to the Circle CI environment, configure a new remote for our repository on Aptible’s platform, and push our branch to Aptible:

    ```sql theme={null}
    jobs:
      git-deploy:
        # # #
        steps:
          - checkout
          - run:
              name: Git push and deploy to Aptible
              command: |
                apt-get update && apt-get install -y git openssh-client
                ssh-keyscan beta.aptible.com >> ~/.ssh/known_hosts
                git remote add aptible git@beta.aptible.com:$APTIBLE_ENVIRONMENT/$APTIBLE_APP.git
                git push aptible $CIRCLE_SHA1:master
    ```

    From there, the procedure for a [Dockerfile-based deployment](/docs/how-to-guides/app-guides/deploy-from-git) remains the same!
  </Tab>

  <Tab title="Travis CI">
    ### Configuring SSH

    To deploy to Aptible via Travis CI, [add your SSH Private Key via the Travis CI repository settings](https://docs.travis-ci.com/user/environment-variables/#defining-variables-in-repository-settings) with the following values:

    * **Name:** `APTIBLE_GIT_SSH_KEY`
    * **Value:** The ***base64-encoded*** contents of the SSH Private Key created in the previous step.

    > ⚠️ Warning
    >
    > The SSH private key added to the Travis CI environment variable must be base64-encoded.

    ### Configuring the Environment

    You also need to set environment variables on your project with the name of your Aptible environment and app, in `APTIBLE_ENVIRONMENT` and `APTIBLE_APP`, respectively. You can add these to your project using [environment variables](https://docs.travis-ci.com/user/environment-variables/#defining-variables-in-repository-settings) on the Travis CI dashboard.

    ### Configuring the Deployment

    Finally, you must configure the Travis CI project to deploy your application to Aptible:

    ```sql theme={null}
    language: generic
    sudo: true

    services:
      - docker

    jobs:
      include:
        - stage: push
          if: branch = travis-deploy
          addons:
            ssh_known_hosts: beta.aptible.com
          before_script:
            - mkdir -p ~/.ssh
            # to save it, cat <<KEY>> | base64 and save that in secrets
            - echo "$APTIBLE_GIT_SSH_KEY" | base64 -d > ~/.ssh/id_rsa
            - chmod 0400 ~/.ssh/id_rsa
            - eval "$(ssh-agent -s)"
            - ssh-add ~/.ssh/id_rsa
            - ssh-keyscan beta.aptible.com >> ~/.ssh/known_hosts

          script:
            - git remote add aptible git@beta.aptible.com:$APTIBLE_ENVIRONMENT/$APTIBLE_APP.git
            - git push aptible $TRAVIS_COMMIT:master
    ```

    Let’s break down how this works. We begin by defining when the deployment should run (when a push is made to the `travis-deploy` branch) and where we are going to deploy (so we add `beta.aptible.com` as a known host):

    ```sql theme={null}
    # # #
    jobs:
      include:
        - stage: push
          if: branch = travis-deploy
          addons:
            ssh_known_hosts: beta.aptible.com
    ```

    The Travis CI configuration then allows us to split our script into two parts, with the `before_script` configuring the Travis CI environment to use our SSH key:

    ```sql theme={null}
          # Continued from above
          before_script:
            - mkdir -p ~/.ssh
            # to save it, cat <<KEY>> | base64 and save that in secrets
            - echo "$APTIBLE_GIT_SSH_KEY" | base64 -d > ~/.ssh/id_rsa
            - chmod 0400 ~/.ssh/id_rsa
            - eval "$(ssh-agent -s)"
            - ssh-add ~/.ssh/id_rsa
            - ssh-keyscan beta.aptible.com >> ~/.ssh/known_hosts
    ```

    Finally, our `script` block configures a new remote for our repository on Aptible’s platform, and pushes our branch to Aptible:

    ```sql theme={null}
          # Continued from above
          script:
            - git remote add aptible git@beta.aptible.com:$APTIBLE_ENVIRONMENT/$APTIBLE_APP.git
            - git push aptible $TRAVIS_COMMIT:master
    ```

    From there, the procedure for a [Dockerfile-based deployment](/docs/how-to-guides/app-guides/deploy-from-git) remains the same!
  </Tab>

  <Tab title="GitLab CI">
    ### Configuring SSH

    To deploy to Aptible via GitLab CI, [add your SSH Private Key via the GitLab CI dashboard](https://docs.gitlab.com/ee/ci/ssh_keys/#ssh-keys-when-using-the-docker-executor) with the following values:

    * **Key:** `APTIBLE_GIT_SSH_KEY`
    * **Value:** The ***base64-encoded*** contents of the SSH Private Key created in the previous step.

    > ⚠️ Warning
    >
    > The SSH private key added to the GitLab CI environment variable must be base64-encoded.

    ### Configuring the Environment

    You also need to set environment variables on your project with the name of your Aptible environment and app, in `APTIBLE_ENVIRONMENT` and `APTIBLE_APP`, respectively. You can add these to your project using [project variables](https://docs.gitlab.com/ee/ci/variables/#add-a-cicd-variable-to-a-project) on the GitLab CI dashboard.

    ### Configuring the Deployment

    Finally, you must configure the GitLab CI pipeline to deploy your application to Aptible:

    ```sql theme={null}
    image: debian:latest

    git_deploy_job:
      only:
        - gitlab-deploy
      before_script:
        - apt-get update && apt-get install -y git
        # taken from: https://docs.gitlab.com/ee/ci/ssh_keys/
        - 'command -v ssh-agent >/dev/null || ( apt-get update -y && apt-get install openssh-client -y )'
        - eval $(ssh-agent -s)
        # to save it, cat <<KEY>> | base64 and save that in secrets
        - echo "$DEMO_APP_APTIBLE_GIT_SSH_KEY" | base64 -d | tr -d '
    ' | ssh-add -
        - mkdir -p ~/.ssh
        - chmod 700 ~/.ssh
      script:
        - |
          ssh-keyscan beta.aptible.com >> ~/.ssh/known_hosts
          git remote add aptible git@beta.aptible.com:$DEMO_APP_APTIBLE_ENVIRONMENT/$DEMO_APP_APTIBLE_APP.git
          git push aptible $CI_COMMIT_SHA:master
    ```

    Let’s break down how this works. We begin by defining when the deployment should run (when a push is made to the `gitlab-deploy` branch), and then we define the `before_script` that will configure SSH in our job environment:

    ```sql theme={null}
      # . . .
      before_script:
        - apt-get update && apt-get install -y git
        # taken from: https://docs.gitlab.com/ee/ci/ssh_keys/
        - 'command -v ssh-agent >/dev/null || ( apt-get update -y && apt-get install openssh-client -y )'
        - eval $(ssh-agent -s)
        - echo "$DEMO_APP_APTIBLE_GIT_SSH_KEY" | base64 -d | tr -d '
    ' | ssh-add -
        - mkdir -p ~/.ssh
        - chmod 700 ~/.ssh
    ```

    Finally, our `script` block configures a new remote for our repository on Aptible’s platform, and pushes our branch to Aptible:

    ```sql theme={null}
      # Continued from above
      script:
        - |
          ssh-keyscan beta.aptible.com >> ~/.ssh/known_hosts
          git remote add aptible git@beta.aptible.com:$DEMO_APP_APTIBLE_ENVIRONMENT/$DEMO_APP_APTIBLE_APP.git
          git push aptible $CI_COMMIT_SHA:master
    ```

    From there, the procedure for a [Dockerfile-based deployment](/docs/how-to-guides/app-guides/deploy-from-git) remains the same!
  </Tab>
</Tabs>

## Deploying with Docker

### Prerequisites

To deploy to Aptible with a Docker image via a CI integration, you should create a robot user to manage your deployment:

1. Create a `Robots` [custom Aptible role](/docs/core-concepts/security-compliance/access-permissions) in your Aptible organization. Grant it "Read" and "Manage" permissions for the environment where you would like to deploy.

2. Invite a new robot user with a valid email address (for example, `deploy@yourdomain.com`) to the `Robots` role.

3. Sign out of your Aptible account, accept the invitation from the robot user's email address, and set a password for the robot's Aptible account.

<Tabs>
  <Tab title="GitHub Actions">
    Some of the below instructions and more information can also be found on the Github Marketplace page for the [Deploy to Aptible Action.](https://github.com/marketplace/actions/deploy-to-aptible#example-with-container-build-and-docker-hub)

    ## Configuring the Environment

    To deploy to Aptible via GitHub Actions, you must first [create encrypted secrets for your repository](https://docs.github.com/en/actions/security-guides/encrypted-secrets#creating-encrypted-secrets-for-a-repository) with Docker registry and Aptible credentials:

    `DOCKERHUB_USERNAME` and `DOCKERHUB_TOKEN`
    The credentials for your private Docker registry (in this case, DockerHub).

    `APTIBLE_USERNAME` and `APTIBLE_PASSWORD`
    The credentials for the robot account created to deploy to Aptible.

    ## Configuring the Workflow

    Additionally, you will need to set some environment variables within the GitHub Actions workflow:

    `IMAGE_NAME`
    The Docker image you wish to deploy from your Docker registry.

    `APTIBLE_ENVIRONMENT`
    The name of the Aptible environment acting as the target for this deployment.

    `APTIBLE_APP`
    The name of the app within the Aptible environment we are deploying with this workflow.

    ## Configuring the Workflow

    Finally, you must configure the workflow to deploy your application to Aptible:

    ```ruby theme={null}
    on:
      push:
        branches: [ main ]

    env:
      IMAGE_NAME: user/app:latest
      APTIBLE_ENVIRONMENT: "my_environment"
      APTIBLE_APP: "my_app"

    jobs:
      deploy:
        runs-on: ubuntu-latest

        steps:
          # Allow multi-platform builds.
          - name: Set up QEMU
            uses: docker/setup-qemu-action@v2

          # Allow use of secrets and other advanced docker features.
          - name: Set up Docker Buildx
            uses: docker/setup-buildx-action@v2

          # Log into Docker Hub
          - name: Login to DockerHub
            uses: docker/login-action@v2
            with:
              username: ${{ secrets.DOCKERHUB_USERNAME }}
              password: ${{ secrets.DOCKERHUB_TOKEN }}

          # Build image using default dockerfile.
          - name: Build and push
            uses: docker/build-push-action@v3
            with:
              push: true
              tags: ${{ env.IMAGE_NAME }}

          # Deploy to Aptible
          - name: Deploy to Aptible
            uses: aptible/aptible-deploy-action@v5
            with:
              username: ${{ secrets.APTIBLE_USERNAME }}
              password: ${{ secrets.APTIBLE_PASSWORD }}
              environment: ${{ env.APTIBLE_ENVIRONMENT }}
              app: ${{ env.APTIBLE_APP }}
              docker_img: ${{ env.IMAGE_NAME }}
              private_registry_username: ${{ secrets.DOCKERHUB_USERNAME }}
              private_registry_password: ${{ secrets.DOCKERHUB_TOKEN }}
    ```
  </Tab>

  <Tab title="TravisCI">
    ## Configuring the Environment

    You also need to set environment variables on your project with the name of your Aptible environment and app, in APTIBLE\_ENVIRONMENT and APTIBLE\_APP, respectively. You can add these to your project using environment variables on the Travis CI dashboard.

    To define how the Docker image is built and deployed, you’ll need to set a few additional variables:

    `APTIBLE_USERNAME` and `APTIBLE_PASSWORD`
    The credentials for the robot account created to deploy to Aptible.

    `APTIBLE_DOCKER_IMAGE`
    The name of the Docker image you wish to deploy to Aptible.

    If you are using a private registry to store your Docker image, you also need to specify credentials to be passed to Aptible:

    `APTIBLE_PRIVATE_REGISTRY_USERNAME`
    The username of the account that can access the private registry containing the Docker image.

    `APTIBLE_PRIVATE_REGISTRY_PASSWORD`
    The password of the account that can access the private registry containing the Docker image.

    ## Configuring the Deployment

    Finally, you must configure the workflow to deploy your application to Aptible:

    ```ruby theme={null}
    language: generic
    sudo: true

    services:
      - docker

    jobs:
      include:
      - stage: build-and-test
        script: |
          make build
          make test
      - stage: push
        if: branch = main
        script: |
          # login to your registry
          docker login \
            -u $APTIBLE_PRIVATE_REGISTRY_EMAIL \
            -p $APTIBLE_PRIVATE_REGISTRY_PASSWORD
          # push your docker image to your registry
          make push

          # download the latest aptible cli and install it
          wget https://omnibus-aptible-toolbelt.s3.amazonaws.com/aptible/omnibus-aptible-toolbelt/latest/aptible-toolbelt_latest_debian-9_amd64.deb && \
            dpkg -i ./aptible-toolbelt_latest_debian-9_amd64.deb && \
            rm ./aptible-toolbelt_latest_debian-9_amd64.deb

          # login and deploy your app
          aptible login \
            --email "$APTIBLE_USERNAME" \
            --password "$APTIBLE_PASSWORD"
          aptible deploy \
            --environment "$APTIBLE_ENVIRONMENT" \
            --app "$APTIBLE_APP"
    ```

    Let’s break down how this works. The script for the `build-and-test` stage does what it says on the label: It builds our Docker image as runs tests on it, as we’ve defined in a Makefile.

    Then, script from the `push` stage pushes our image to the Docker registry:

    ```ruby theme={null}
    # login to your registry
    docker login \
      -u $APTIBLE_PRIVATE_REGISTRY_EMAIL \
      -p $APTIBLE_PRIVATE_REGISTRY_PASSWORD
    # push your docker image to your registry
    make push
    ```

    Finally, it installs the Aptible CLI in the Travis CI build environment, logs in to Aptible, and deploys your Docker image to the specified envrionment and app:

    ```ruby theme={null}
    # download the latest aptible cli and install it
    wget https://omnibus-aptible-toolbelt.s3.amazonaws.com/aptible/omnibus-aptible-toolbelt/aptible-toolbelt-latest_amd64.deb && \
      dpkg -i ./aptible-toolbelt-latest_amd64.deb && \
      rm ./aptible-toolbelt-latest_amd64.deb

    # login and deploy your app
    aptible login \
      --email "$APTIBLE_USERNAME" \
      --password "$APTIBLE_PASSWORD"
    aptible deploy \
      --environment "$APTIBLE_ENVIRONMENT" \
      --app "$APTIBLE_APP"
    ```
  </Tab>
</Tabs>

From there, you can review our resources for [deploying via Docker image!](/docs/how-to-guides/app-guides/migrate-dockerfile-to-direct-image-deploy)


# How to scale apps and services
Source: https://www.aptible.com/docs/how-to-guides/app-guides/how-to-scale-apps-services



Learn how to manually scale apps and services on Aptible

## Overview

[Apps](/docs/core-concepts/apps/overview) can be scaled on a [Service](/docs/core-concepts/apps/deploying-apps/services)-by-Service basis: any given Service for your App can be scaled independently of others.

## Using the Dashboard

* Within the Aptible Dashboard apps and services can be manually scaled by:

  * Navigating to the Environment in which your App lives

  * Selecting the **Apps** tab

  * Selecting the respective App

  * Selecting **Scale**

<img alt="" />

## Using the CLI

Apps and services can be manually scaled via the Aptible CLI using the [`aptible apps:scale`](/docs/reference/aptible-cli/cli-commands/cli-apps-scale) command.

## Using Terraform

Apps and services can be scaled programmatically via Aptible [Terraform Provider](https://registry.terraform.io/providers/aptible/aptible/latest/docs) by using the nested service element for the App resource:

```js theme={null}
resource "aptible_app" "APP" {
    env_id = ENVIRONMENT_ID
    handle = "APP_HANDLE"
    service {
        process_type = "SERVICE_NAME1"
        container_count = 1
        container_memory_limit = 1024
    }
    service {
        process_type = "SERVICE_NAME2"
        container_count = 2
        container_memory_limit = 2048
    }
}
```


# How to use AWS Secrets Manager with Aptible Apps
Source: https://www.aptible.com/docs/how-to-guides/app-guides/how-to-use-aws-secrets-manager

Learn how to use AWS Secrets Manager with Aptible Apps

# Overview

AWS Secrets Manager is a secure and centralized solution for managing sensitive data like database credentials and API keys. This guide provides an example of how to set up AWS Secrets Manager to store and retreive secrets into an Aptible App. This reference example uses a Rails app, but this can be used in conjunction with any app framework supported by AWS SDKs.

# **Steps**

### **Store Secrets in AWS Secrets Manager**

* Log in to the AWS Console.

* Navigate to `Secrets Manager`.

* Click Store a new secret.

* Select Other type of secret.

* Enter your key-value pairs (e.g., `DATABASE_PASSWORD`, `API_KEY`).

* Click Next and provide a Secret Name (e.g., `myapp/production`).

* Complete the steps to store the secret.

### **Set Up IAM Permissions**

Set up AWS Identity and Access Management (IAM) objects to grant access to the secret from your Aptible app.

***Create a Custom IAM Policy***: for better security, create a custom policy that grants only the necessary permissions.

* Navigate to IAM in the AWS Console, and click on Create policy

* In the Create Policy page, select the JSON tab.

* Paste the following policy JSON:

```json theme={null}
{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "AllowSecretsManagerReadOnlyAccess",
      "Effect": "Allow",
      "Action": [
        "secretsmanager:GetSecretValue",
        "secretsmanager:DescribeSecret"
      ],
      "Resource": "*"
    }
  ]
}
```

* Click Review policy.

* Enter a Name for the policy (e.g., `SecretsManagerReadOnlyAccess`).

* Click Create policy.

***Note***: the example IAM policy above grants access to all secrets in the account via `"Resource": "*"`. You may additionally opt to restrict access to specific secrets for better security. An example of restricting access to a specific secret:

```yaml theme={null}
"Resource": "arn:aws:secretsmanager:us-east-1:123456789012:secret:myapp/production"
```

***Create an IAM User***

* Log in to your AWS Management Console.

* Navigate to the IAM (Identity and Access Management) service.

* In the left sidebar, click on Users, then click Add users.

* Configure the following settings:

  * User name: Enter a username (e.g., secrets-manager-user).

  * Access type: Select Programmatic access.

* Click Next: Permissions.

* To attach an existing policy, search for your newly created policy (SecretsManagerReadOnlyAccess) and check the box next to it.

***Generate API Keys for the IAM User***

* In the IAM dashboard, click on "Users" in the left navigation pane.

* Click on the username of the IAM user for whom you want to generate API keys.

* Go to Security Credentials. Within the user's summary page, select the "Security credentials" tab.

* Scroll down to the "Access keys" section.

* Click on the "Create access key" button.

* Choose the appropriate access key type (typically "Programmatic access").

* Download the Credentials: After the access key is created, click on "Download .csv file" to save the Access Key ID and Secret Access Key securely. Important: This is the only time you can view or download the secret access key. Keep it in a secure place.

### **Set Up AWS Credentials on Aptible**

Aptible uses environment variables for configuration. Set the following AWS credentials:

```bash theme={null}
AWS_ACCESS_KEY_ID
AWS_SECRET_ACCESS_KEY
AWS_REGION (e.g., us-east-1)
```

To set environment variables in Aptible:

* Log in to your Aptible Dashboard.

* Select your app and navigate to the Configuration tab.

* Add the AWS credentials as environment variables.

### **Add AWS SDK to Your Rails App**

Add the AWS SDK gem to interact with AWS Secrets Manager:

```ruby theme={null}
# Gemfile
gem 'aws-sdk-secretsmanager'
```

Run:

```bash theme={null}
bundle install
```

### **Create a Service to Fetch Secrets**

Create a service object that fetches secrets from AWS Secrets Manager.

```ruby theme={null}
# app/services/aws_secrets_manager_service.rb
require 'aws-sdk-secretsmanager'

class AwsSecretsManagerService
  def initialize(secret_name:, region:)
    @secret_name = secret_name
    @region = region
  end

  def fetch_secrets
    client = Aws::SecretsManager::Client.new(region: @region)
    secret_value = client.get_secret_value(secret_id: @secret_name)

    secrets = if secret_value.secret_string
                JSON.parse(secret_value.secret_string)
              else
                JSON.parse(Base64.decode64(secret_value.secret_binary))
              end

    secrets.transform_keys { |key| key.upcase }
  rescue Aws::SecretsManager::Errors::ServiceError => e
    Rails.logger.error "AWS Secrets Manager Error: #{e.message}"
    {}
  end
end
```

### **Initialize Secrets at Startup**

Create an initializer to load secrets when the app starts.

```ruby theme={null}
# config/initializers/load_secrets.rb
if Rails.env.production?
  secret_name = 'myapp/production' # Update with your secret name
  region = ENV['AWS_REGION']

  secrets_service = AwsSecretsManagerService.new(secret_name: secret_name, region: region)
  secrets = secrets_service.fetch_secrets

  ENV.update(secrets) if secrets.present?
end
```

### **Use Secrets in Your App**

Access the secrets via ENV variables.

Example: Database Configuration

```yaml theme={null}
# config/database.yml
production:
  adapter: postgresql
  encoding: unicode
  host: <%= ENV['DATABASE_HOST'] %>
  database: <%= ENV['DATABASE_NAME'] %>
  username: <%= ENV['DATABASE_USERNAME'] %>
  password: <%= ENV['DATABASE_PASSWORD'] %>
```

Example: API Key Usage

```ruby theme={null}
# app/services/external_api_service.rb
class ExternalApiService
  API_KEY = ENV['API_KEY']

  def initialize
    # Use API_KEY in your requests
  end
end
```


# Circle CI
Source: https://www.aptible.com/docs/how-to-guides/app-guides/integrate-aptible-with-ci/circle-cl



Once you've completed the steps for [CI Integration](/docs/how-to-guides/app-guides/integrate-aptible-with-ci/overview), set up Circle CI as follows:

**Step 1:** Add the private key you created for the robot user to your Circle CI project through the **Project Settings > SSH keys** page on Circle CI.

**Step 2:** Add a custom deploy step that pushes to Aptible following Circle's [deployment instructions](https://circleci.com/docs/configuration#deployment). It should look something like this (adjust branch names as needed):

```ruby theme={null}
deployment:
  production:
    branch: production
    commands:
      - git fetch --depth=1000000
      - git push git@beta.aptible.com:$ENVIRONMENT_HANDLE/$APP_HANDLE.git $CIRCLE_SHA1:master
```

> 📘 In the above example, `git@beta.aptible.com:$ENVIRONMENT_HANDLE/$APP_HANDLE.git` represents your App's Git Remote.

> Also, see [My deploy failed with a git error referencing objects, trees, revisions or commits](/docs/how-to-guides/troubleshooting/common-errors-issues/git-reference-error) to understand why you need `git fetch` here.


# Codeship
Source: https://www.aptible.com/docs/how-to-guides/app-guides/integrate-aptible-with-ci/codeship



You don't need to create a new SSH public key for your robot user when using Codeship. Once you've completed the steps for [CI Integration](/docs/how-to-guides/app-guides/integrate-aptible-with-ci/overview), set up Codeship as follows:

**Step 1:** Copy the public key from your Codeship project's General Settings page, and add it as a [new key](/docs/core-concepts/security-compliance/authentication/ssh-keys) for your robot user.

**Step 2:** Add a Custom Script deployment in Codeship with the following commands:

```bash theme={null}
git fetch --depth=1000000
git push git@beta.aptible.com:$ENVIRONMENT_HANDLE/$APP_HANDLE.git $CI_COMMIT_ID:master
```

> 📘 In the above example, `git@beta.aptible.com:$ENVIRONMENT_HANDLE/$APP_HANDLE.git` represents your App's Git Remote.

> Also, see [My deploy failed with a git error referencing objects, trees, revisions or commits](/docs/how-to-guides/troubleshooting/common-errors-issues/git-reference-error) to understand why you need `git fetch` here.


# Jenkins
Source: https://www.aptible.com/docs/how-to-guides/app-guides/integrate-aptible-with-ci/jenkins



Once you've completed the steps for [CI Integration](/docs/how-to-guides/app-guides/integrate-aptible-with-ci/overview), set up Jenkins using these steps:

1. In Jenkins, using the Git plugin, add a new repository to your build:

   1. For the Repository URL, use your App's Git Remote

   2. Upload the private key you created for your robot user as a credential.

   3. Under "Advanced...", name this repository `aptible`.

2. Then, add a post-build "Git Publisher" trigger, to deploy to the `master` branch of your newly-created `aptible` remote.


# How to integrate Aptible with CI Platforms
Source: https://www.aptible.com/docs/how-to-guides/app-guides/integrate-aptible-with-ci/overview



At a high level, integrating Aptible with your CI platform boils down to the following steps:

* Create a robot [User](/docs/core-concepts/security-compliance/access-permissions) in Aptible for your CI platform.

* Trigger a deploy to Aptible whenever your CI process completes. How you do this depends on [how you're deploying to Aptible](/docs/core-concepts/apps/deploying-apps/image/overview):

## Creating a Robot User

1. Create a "Robots" [custom role](/docs/core-concepts/security-compliance/access-permissions) in your Aptible [organization](/docs/core-concepts/security-compliance/access-permissions), and grant it "Full Visibility" and "Deployment" [permissions](/docs/core-concepts/security-compliance/access-permissions) for the [environment](/docs/core-concepts/architecture/environments) where you will be deploying.

2. Invite a new user to this Robots role. This user needs to have an actual email address. You can use something like `deploy@yourdomain.com`.

3. Log out of your Aptible account, accept the invitation you received for the robot user by email, and create a password for the robot user.

Suppose you use this user to deploy an app via Git. In that case, you're also going to need an SSH keypair for the robot user to let them connect to your app's [Git Remote](/docs/core-concepts/apps/deploying-apps/image/deploying-with-git/overview#git-remote):

1. Generate an SSH key pair for the robot user using `ssh-keygen -f deploy.pem`. Don't set a password for the key.

2. Register the [SSH Public Key](/docs/core-concepts/security-compliance/authentication/ssh-keys) with Aptible for the robot user.

## Triggering a Deploy

Ensure image security by catching issues before deployment and continually scanning images between deployments. See [Image and Vulnerability Scanning](/docs/how-to-guides/platform-guides/image-vulnerability-scanning) for the recommended process.

## Deploying via Git

Most CI platforms expose a form of "after-success" hook you can use to trigger a deploy to Aptible after your tests have passed. You'll need to use it to trigger a deploy to Aptible by running `git push`. For the `git push` to work, you'll also need to provide your CI platform with the SSH key you created for your robot user. To that end, most CI platforms let you provide encrypted files to store in your repository.

## Deploying via Docker image

To deploy via Docker image:

1. Build and publish a Docker Image when your build succeeds.

2. Install the [Aptible CLI](/docs/reference/aptible-cli/cli-commands/overview) in your CI environment.

3. Log in as the robot user, and use [`aptible deploy`](/docs/reference/aptible-cli/cli-commands/cli-deploy) to trigger a deploy to Aptible.

***

**Keep reading**

* [Circle CI](/docs/how-to-guides/app-guides/integrate-aptible-with-ci/circle-cl)
* [Codeship](/docs/how-to-guides/app-guides/integrate-aptible-with-ci/codeship)
* [Jenkins](/docs/how-to-guides/app-guides/integrate-aptible-with-ci/jenkins)
* [Travis CI](/docs/how-to-guides/app-guides/integrate-aptible-with-ci/travis-cl)


# Travis CI
Source: https://www.aptible.com/docs/how-to-guides/app-guides/integrate-aptible-with-ci/travis-cl



Once you've completed the steps for [CI Integration](/docs/how-to-guides/app-guides/integrate-aptible-with-ci/overview), set up Travis CI as follows:

**Step 1:** Encrypt the private key you created for the robot user and store it in the repo. To do so, follow Travis CI's [instructions on encrypting files](http://docs.travis-ci.com/user/encrypting-files/). We recommend using the "Automated Encryption" method.

**Step 2:** Add an `after_success` deploy step. Here again, follow Travis CI's [instructions on custom deployment](http://docs.travis-ci.com/user/deployment/custom/). The `after_success` in your `.travis.yml` file should look like this:

```ruby theme={null}
after_success:
  - git fetch --depth=1000000
  - chmod 600 .travis/deploy.pem
  - ssh-add .travis/deploy.pem
  - git remote add aptible git@beta.aptible.com:$ENVIRONMENT_HANDLE/$APP_HANDLE.git
  - git push aptible master
```

<Tip> 📘 In the above example, `git@beta.aptible.com:$ENVIRONMENT_HANDLE/$APP_HANDLE.git` represents your App's Git Remote. </Tip>

> Also, see [My deploy failed with a git error referencing objects, trees, revisions or commits](/docs/how-to-guides/troubleshooting/common-errors-issues/git-reference-error) to understand why you need `git fetch` here.


# How to make Git deploys faster
Source: https://www.aptible.com/docs/how-to-guides/app-guides/make-docker-deploys-faster



Make [deploying via Git](/docs/how-to-guides/app-guides/deploy-from-git) faster by structuring your Dockerfile to maximize efficiency by leveraging the Docker build cache:

## Gems installed via Bundler

In order for the Docker build cache to cache gems installed via Bundler:

1. Add the Gemfile and Gemfile.lock files to the image.

2. Run `bundle install`, *before* adding the rest of the repo (via `ADD .`).

Here's an example of how that might look in a Dockerfile:

```ruby theme={null}
FROM ruby

# If needed, install system dependencies here

# Add Gemfile and Gemfile.lock first for caching
ADD Gemfile /app/
ADD Gemfile.lock /app/
WORKDIR /app
RUN bundle install

ADD . /app

# If needed, add additional RUN commands here
```

## Packages installed via NPM

In order for the Docker build cache to cache packages installed via npm:

1. Add the `package.json` file to the image.

2. Run `npm install`, *before* adding the rest of the repo (via `ADD .`).

Here's an example of how that might look in a Dockerfile:

```node theme={null}
FROM node

# If needed, install system dependencies here

# Add package.json before rest of repo for caching
ADD package.json /app/
WORKDIR /app
RUN npm install

ADD . /app

# If needed, add additional RUN commands here
```

## Packages installed via PIP

In order for the Docker build cache to cache packages installed via pip:

1. Add the `requirements.txt` file to the image.

2. Run `pip install`, *before* adding the rest of the repo (via `ADD .`).

Here's an example of how that might look in a Dockerfile:

```python theme={null}
FROM python

# If needed, install system dependencies here

# Add requirements.txt before rest of repo for caching
ADD requirements.txt /app/
WORKDIR /app
RUN pip install -r requirements.txt

ADD . /app
```


# How to migrate from deploying via Git to deploying via Docker image
Source: https://www.aptible.com/docs/how-to-guides/app-guides/migrate-dockerfile-to-direct-image-deploy



Deploying via Docker image lets you build once, [scan that exact artifact in CI](/docs/how-to-guides/platform-guides/image-vulnerability-scanning), and deploy the same image to staging and production.

If you are currently using [deploying via Git](/docs/how-to-guides/app-guides/deploy-from-git) and would like to migrate to deploying via Docker image, use the following instructions:

1. If you have a `Procfile` or `.aptible.yml` file in your repository, you must embed it in your Docker image. To do so, follow the instructions at [Procfiles and `.aptible.yml` with deploying via Docker image](/docs/core-concepts/apps/deploying-apps/image/deploying-with-docker-image/procfile-aptible-yml-direct-docker-deploy).

2. If you modified your image to add the `Procfile` or `.aptible.yml`, rebuild your image and push it again.

3. Deploy using `aptible deploy` as documented in [Using `aptible deploy`](/docs/reference/aptible-cli/cli-commands/cli-deploy), with one exception: the first time you deploy (you don't need to do it again), add the `--git-detach` flag to this command.


# All App Guides
Source: https://www.aptible.com/docs/how-to-guides/app-guides/overview

Explore guides for deploying and managing Apps on Aptible

* [How to create an app](/docs/how-to-guides/app-guides/how-to-create-app)
* [How to scale apps and services](/docs/how-to-guides/app-guides/how-to-scale-apps-services)
* [How to set and modify configuration variables](/docs/how-to-guides/app-guides/set-modify-config-variables)
* [How to deploy to Aptible with CI/CD](/docs/how-to-guides/app-guides/how-to-deploy-aptible-ci-cd)
* [How to define services](/docs/how-to-guides/app-guides/define-services)
* [How to deploy via Docker Image](/docs/how-to-guides/app-guides/deploy-docker-image)
* [How to deploy from Git](/docs/how-to-guides/app-guides/deploy-from-git)
* [How to migrate from deploying via Docker Image to deploying via Git](/docs/how-to-guides/app-guides/deploying-docker-image-to-git)
* [How to integrate Aptible with CI Platforms](/docs/how-to-guides/app-guides/integrate-aptible-with-ci/overview)
* [How to synchronize configuration and code changes](/docs/how-to-guides/app-guides/synchronize-config-code-changes)
* [How to migrate from deploying via Git to deploying via Docker image](/docs/how-to-guides/app-guides/migrate-dockerfile-to-direct-image-deploy)
* [Deploy Metric Drain with Terraform](/docs/how-to-guides/app-guides/deploy-metric-drain-with-terraform)
* [Getting Started with Docker](/docs/how-to-guides/app-guides/getting-started-with-docker)
* [How to access configuration variables during Docker build](/docs/how-to-guides/app-guides/access-config-vars-during-docker-build)
* [How to migrate a NodeJS app from Heroku to Aptible](/docs/how-to-guides/app-guides/migrate-nodjs-from-heroku-to-aptible)
* [How to generate certificate signing requests](/docs/how-to-guides/app-guides/generate-certificate-signing-requests)
* [How to expose a web app to the Internet](/docs/how-to-guides/app-guides/expose-web-app-to-internet)
* [How to set up Cloudflare with Aptible Endpoints](/docs/how-to-guides/app-guides/set-up-cloudflare-with-aptible-endpoints)
* [How to use Nginx with Aptible Endpoints](/docs/how-to-guides/app-guides/use-nginx-with-aptible-endpoints)
* [How to make Git deploys faster](/docs/how-to-guides/app-guides/make-docker-deploys-faster)
* [How to use Domain Apex with Endpoints](/docs/how-to-guides/app-guides/use-domain-apex-with-endpoints/overview)
* [How to use S3 to accept file uploads](/docs/how-to-guides/app-guides/use-s3-to-accept-file-uploads)
* [How to use cron to run scheduled tasks](/docs/how-to-guides/app-guides/use-cron-to-run-scheduled-tasks)
* [How to serve static assets](/docs/how-to-guides/app-guides/serve-static-assets)
* [How to establish client certificate authentication](/docs/how-to-guides/app-guides/establish-client-certificiate-auth)


# How to serve static assets
Source: https://www.aptible.com/docs/how-to-guides/app-guides/serve-static-assets



> 📘 This article is about static assets served by your app such as CSS or JavaScript files. If you're looking for strategies for storing files uploaded by or generated for your customers, see [How do I accept file uploads when using Aptible?](/docs/how-to-guides/app-guides/use-s3-to-accept-file-uploads) instead.

Broadly speaking, there are two ways to serve static assets from an Aptible web app:

## Serving static assets from a web container running on Aptible

> ❗️ This approach is typically only appropriate for development and staging apps. See [Serving static assets from a third-party object store or CDN](/docs/how-to-guides/app-guides/serve-static-assets#serving-static-assets-from-a-third-party-object-store-or-cdn) to understand why and review a production-ready approach. Note that using a third-party object store is often simpler to maintain as well.

Using this method, you'll serve assets from the same web container that is serving application requests on Aptible.

Many web frameworks (such as Django or Rails) have asset serving mechanisms that you can use to build assets, and will automatically serve assets for you after you've done so.

Typically, you'll have to run an asset pre-compilation step ahead of time for this to work. Ideally, you want do so in your `Dockerfile` to ensure the assets are built once and are available in your web containers.

Unfortunately, in many frameworks, building assets requires access to at least a subset of your app's configuration (e.g., for Rails, at the very least, you'll need `RAILS_ENV` to be set, perhaps more depending on your app), but building Docker images is normally done **without configuration**.

Here are a few solutions you can use to work around this problem:

## Use Aptible's `.aptible.env`

If you are building on Aptible by [deploying via Git](/docs/how-to-guides/app-guides/deploy-from-git), you can access your app's configuration variables during the build. This means you can load those variables, then build your assets.

To do so with a Rails app, you'd want to add this block toward the end of your `Dockerfile`:

```bash theme={null}
RUN set -a \
 && . ./.aptible.env \
 && bundle exec rake assets:precompile
```

For a Django app, you might use something like this:

```bash theme={null}
RUN set -a \
 && . ./.aptible.env \
 && python manage.py collectstatic
```

> 📘 Review [Accessing Configuration variables during the Docker build](/docs/how-to-guides/app-guides/access-config-vars-during-docker-build) for more information about `.aptible.env` and important caveats.

## Build assets upon container startup

An alternative is to build assets when your web container starts. If your app has a [Procfile](/docs/how-to-guides/app-guides/define-services), you can do so like this, for example (adjust as needed):

```bash theme={null}
# Rails example:
web: bundle exec rake assets:precompile && exec bundle exec rails s -b 0.0.0.0 -p 3000

# Django example:
web: python manage.py collectstatic && exec gunicorn --access-logfile=- --error-logfile=- --bind=0.0.0.0:8000 --workers=3 mysite.wsgi
```

Alternatively, you could add an `ENTRYPOINT` in your image to do the same thing.

An upside of this approach is that all your configuration variables will be available when the container starts, so this approach is largely guaranteed to work as long as there is no bug in your app.

However, an important downside of this approach is that it will slow down the startup of your containers: instead of building assets once and for all when building your image, your app will rebuild them every time it starts. This includes restarts triggered by [Container Recovery](/docs/core-concepts/architecture/containers/container-recovery) should your app crash.

Overall, this approach is only suitable if your asset build is fairly quick and/or you can tolerate a slower startup.

## Minimize environment requirements and provide them in the Dockerfile

Alternatively, you can refactor your App not to require environment variables to build assets.

For a Django app, you'd typically do that by creating a minimal settings module dedicated to building assets and settings, e.g., `DJANGO_SETTINGS_MODULE=myapp.static_settings` prior to running `collectstatic`

For a Rails app, you'd do that by creating a minimal `RAILS_ENV` dedicated to building assets and settings e.g. `RAILS_ENV=assets` prior to running `assets:precompile`.

If you can take the time to refactor your App slightly, this approach is by far the best one if you are going to serve assets from your container.

## Serving static assets from a third-party object store or CDN

## Reasons to use a third-party object store

There are two major problems with serving assets from your web containers:

### Performance

If you serve your assets from your web containers, you'll typically do so from your application server (e.g. Unicorn for Ruby, Gunicorn for Python, etc.).

However, application servers are optimized for serving application code, not assets. Serving assets is a comparatively dumb task that simpler web servers are better suited for.

For example, when it comes to serving assets, a Unicorn Ruby server serving assets from Ruby code is going to be very inefficient compared to an Nginx or Apache web server.

Likewise, an object store will be a lot more efficient at serving assets than your application server, which is one reason why you should favor using one.

### Interaction with Zero-Downtime Deploys

When you deploy your app, [Zero-Downtime Deployment](/docs/core-concepts/apps/connecting-to-apps/app-endpoints/https-endpoints/overview#zero-downtime-deployment) requires that there will be a period when containers from both your old code release and new code release are serving traffic at the same time.

If you are serving assets from a web container, this means the following interaction could happen:

1. A client requests a page.

2. That request is routed to a container running your new code, which responds with a page that links to assets.

3. The client requests a linked asset.

4. That request is routed to a container running your old code.

When this interaction happens, if you change your assets, the asset served by your Container running the old code may not be the one you expect. And, if you fingerprint your assets, it may not be found at all.

For your client, both cases will result in a broken page

Using an object store solves this problem: as long as you fingerprint assets, you can ensure your object store is able to serve assets from *all* your code releases.

To do so, simply upload all assets to the object store of your choice for a release prior to deploying it, and never remove assets from past releases until you're absolutely certain they're no longer referenced anywhere.

This is another reason why you should be using an object store to serve static assets.

> 📘 Considering the low pricing of object stores and the relatively small size of most application assets, you might not need to bother with cleaning up older assets: keeping them around may cost you only a few cents per month.

## How to use a third-party object store

To push assets to an object store from an app on Aptible, you'll need to:

* Identify and incorporate a library that integrates with your framework of choice to push assets to the object store of your choice. There are many of those for the most popular frameworks.

* Add credentials for the object store in your App's [Configuration](/docs/core-concepts/apps/deploying-apps/configuration).

* Build and push assets to the object store as part of your release on Aptible. The easiest and best way to do this is to run your asset build and push as part of [`before_release`](/docs/core-concepts/apps/deploying-apps/releases/aptible-yml#before-release) commands on Aptible.

For example, if you're running a Rails app and using [the Asset Sync gem](https://github.com/rumblelabs/asset_sync) to automatically sync your assets to S3 at the end of the Rails assets pipeline, you might use the following [`.aptible.yml`](/docs/core-concepts/apps/deploying-apps/releases/aptible-yml) file:

```bash theme={null}
before_release:
  - bundle exec rake assets:precompile
```


# How to set and modify configuration variables
Source: https://www.aptible.com/docs/how-to-guides/app-guides/set-modify-config-variables



Learn how to set and modify app [configuration variables](/docs/core-concepts/apps/deploying-apps/configuration). Setting or modifying app configuration variables always restarts the app to apply the changes. Follow our [synchronize configuration and code changes guide](/docs/how-to-guides/app-guides/synchronize-config-code-changes) to update the app configuration and deploy code using a single deployment.&#x20;

## Using the Dashboard

Configuration variables can be set or modified in the Dashboard in the following ways:

* While deploying new code by:

  * Using the [**Deploy**](https://app.aptible.com/create) tool will allow you to set environment variables as you deploy your code <img alt="" />

* For existing apps by:

  * Navigating to the respective app

  * Selecting the **Configuration** tab

  * Selecting **Edit** within Edit Environment Variables <img alt="" />

## Using the CLI

Configuration variables can be set or modified via the CLI in the following ways:

* Using [`aptible deploy`](/docs/reference/aptible-cli/cli-commands/cli-deploy) command

* Using the [`aptible config:set`](/docs/reference/aptible-cli/cli-commands/cli-config-set) command

## Size Limits

A practical limit for configuration variable length is 65,536 characters.


# Set Up Cloudflare with Aptible Endpoints
Source: https://www.aptible.com/docs/how-to-guides/app-guides/set-up-cloudflare-with-aptible-endpoints

Configure Cloudflare in front of Aptible Endpoints while preserving TLS validation and traffic routing.

You can use Cloudflare as a proxy in front of an Aptible [Endpoint](/docs/core-concepts/apps/connecting-to-apps/app-endpoints/overview), but the DNS setup needs to preserve Aptible's [Managed TLS](/docs/core-concepts/apps/connecting-to-apps/app-endpoints/managed-tls) validation records and route traffic through a stable origin hostname.

## Recommended Domain Structure

Use separate hostnames for the Aptible origin and the Cloudflare-facing URL:

* Aptible origin: `app.origin.example.com`
* Public Cloudflare URL: `app.example.com`

The origin hostname points to the Aptible Endpoint. The public hostname points to the origin hostname through Cloudflare.

## Configuration Steps

<Steps>
  <Step title="Configure Managed TLS for the origin hostname">
    In Aptible, configure the Endpoint custom domain as the origin hostname, such as `app.origin.example.com`. Create the [ACME validation records](/docs/how-to-guides/app-guides/expose-web-app-to-internet#validation-records) shown in the Endpoint's Managed TLS configuration.
  </Step>

  <Step title="Create the origin CNAME in Cloudflare">
    Create a DNS-only CNAME record from the origin hostname to the Aptible Endpoint hostname:

    ```text theme={null}
    app.origin.example.com -> elb-xxx.aptible.in
    ```

    Leave Cloudflare proxying disabled for this origin record.
  </Step>

  <Step title="Create the public CNAME in Cloudflare">
    Create a proxied CNAME record from the public hostname to the origin hostname:

    ```text theme={null}
    app.example.com -> app.origin.example.com
    ```
  </Step>

  <Step title="Restrict direct origin access">
    Enable [IP filtering](/docs/core-concepts/apps/connecting-to-apps/app-endpoints/ip-filtering) on the Aptible Endpoint and allow Cloudflare's published IP ranges so traffic reaches the origin through Cloudflare.
  </Step>
</Steps>

## Important Notes

Do not point the public hostname directly at Aptible's ACME validation records. ACME records are used only for certificate validation, not for serving application traffic.

Do not create DNS `A` records that point directly to Aptible Endpoint IP addresses. Endpoint IP addresses can change, which would make those records stale.

<Info>
  Cloudflare's Universal SSL certificate typically covers one level of subdomains. If you use multiple subdomain levels, such as `beta.staging.example.com`, you may need an Advanced Certificate from Cloudflare.
</Info>

## Related Documentation

* [Custom Domain](/docs/core-concepts/apps/connecting-to-apps/app-endpoints/custom-domain)
* [Managed TLS](/docs/core-concepts/apps/connecting-to-apps/app-endpoints/managed-tls)
* [IP Filtering](/docs/core-concepts/apps/connecting-to-apps/app-endpoints/ip-filtering)


# How to synchronize configuration and code changes
Source: https://www.aptible.com/docs/how-to-guides/app-guides/synchronize-config-code-changes



Updating the [configuration](/docs/core-concepts/apps/deploying-apps/configuration) of your [app](/docs/core-concepts/apps/overview) using [`aptible config:set`](/docs/reference/aptible-cli/cli-commands/cli-config-set) then deploying your app via Git or via Docker image will deploy your app twice:

* Once to apply the [Configuration](/docs/core-concepts/apps/deploying-apps/configuration) changes.
* Once to deploy the new [Image](/docs/core-concepts/apps/deploying-apps/image/overview).

This process may be inconvenient when you need to update your configuration and ship new code that depends on the updated configuration **simultaneously**. To solve this problem, the Aptible CLI lets you deploy and update your app configuration as one atomic operation.

## For deploying via Git

To synchronize a Configuration change and code release when [deploying via Git](/docs/how-to-guides/app-guides/deploy-from-git):

**Step 1:** Push your code to a new deploy branch on Aptible. Any name will do, as long as it's not `master`, but we recommend giving it a random-ish name like in the example below. Pushing to a branch other than `master` will **not** trigger a deploy on Aptible. However, the new code will be available for future deploys.

```js theme={null}
BRANCH="deploy-$(date "+%s")"
git push aptible "master:$BRANCH"
```

**Step 2:** Deploy this branch along with the new Configuration variables using the [`aptible deploy`](/docs/reference/aptible-cli/cli-commands/cli-deploy) command:

```js theme={null}
aptible deploy \
  --app "$APP_HANDLE" \
  --git-commitish "$BRANCH" \
  FOO=BAR QUX=
```

Please note that you can provide some common configuration variables as arguments to CLI commands instead of updating the app configuration. For example, if you need to include [Private Registry Authentication](/docs/core-concepts/apps/overview) credentials to let Aptible pull a source Docker image, you can use this command:

```js theme={null}
aptible deploy \
  --app "$APP_HANDLE" \
  --git-commitish "$BRANCH" \
  --private-registry-username "$USERNAME" \
  --private-registry-password "$PASSWORD"
```

## For deploying via Docker image

Please use the [`aptible deploy`](/docs/reference/aptible-cli/cli-commands/cli-deploy) CLI command to deploy your app if you are [deploying via Docker image](/docs/how-to-guides/app-guides/migrate-dockerfile-to-direct-image-deploy). If you are not using `aptible deploy`, please review the [deploying via Docker image](/docs/how-to-guides/app-guides/migrate-dockerfile-to-direct-image-deploy) instructions. When using `aptible deploy` with deploying via Docker image, you may append environment variables to the [`aptible deploy`](/docs/reference/aptible-cli/cli-commands/cli-deploy) command:

```js theme={null}
aptible deploy \
  --app "$APP_HANDLE" \
  --docker-image "$DOCKER_IMAGE" \
  FOO=BAR QUX=
```


# How to use cron to run scheduled tasks
Source: https://www.aptible.com/docs/how-to-guides/app-guides/use-cron-to-run-scheduled-tasks

Learn how to use cron to run and automate scheduled tasks on Aptible

## Overview

Cron jobs can be used to run, and automate scheduled tasks. On Aptible, users can run cron jobs with the use of an individual app or with a service associated with an app, defined in the app's [procfile](/docs/how-to-guides/app-guides/define-services).

[Supercronic](https://github.com/aptible/supercronic) is an open-source tool created by Aptible that avoids common issues with cron job implementation in containerized platforms.

This guide is designed to walk you through getting started with cron jobs on Aptible with the use of Supercronic.

## Getting Started

**Step 1:** Install [Supercronic](https://github.com/aptible/supercronic#installation) in your Docker image.

**Step 2:** Add a `crontab` to your repository. Here is an example `crontab` you might want to adapt or reuse:

```bash theme={null}
# Run every minute
*/1 * * * * bundle exec rake some:task

# Run once every hour
@hourly curl -sf example.com >/dev/null && echo 'got example.com!'
```

> 📘 For a complete crontab reference, review the documentation from the library Supercronic uses to parse crontabs, [cronexpr](https://github.com/gorhill/cronexpr#implementation).

> 📘 Unless you've specified otherwise with the `TZ` [environment variable](/docs/core-concepts/architecture/containers/overview), the schedule for your crontab will be interpreted in UTC.

**Step 3:** Copy the `crontab` to your Docker image with a directive such as this one:

```bash theme={null}
ADD crontab /app/crontab
```

> 📘 The example above grabs a file named `crontab` found at the root of your repository and copies it under `/app` in your image. Adjust as needed.

**Step 4:** Add a new service (if your app already has a Procfile), or deploy a new app altogether to start Supercronic and run your cron jobs. If you are adding a service, use this `Procfile` declaration:

```bash theme={null}
cron: exec /usr/local/bin/supercronic /app/crontab
```

If you are adding a new app, you can use the same `Procfile` declaration or add a `CMD` declaration to your [Dockerfile](/docs/core-concepts/apps/deploying-apps/image/deploying-with-git/overview):

```bash theme={null}
CMD ["supercronic", "/app/crontab"]
```


# AWS Domain Apex Redirect
Source: https://www.aptible.com/docs/how-to-guides/app-guides/use-domain-apex-with-endpoints/aws-domain-apex-redirect

This tutorial will guide you through the process of setting up an Apex redirect using AWS S3, AWS CloudFront, and AWS Certificate Manager.

The heavy lifting is automated using CloudFormation, so this entire process shouldn't require more than a few minutes of active work.

Before starting, you will need the following:

* The domain you want to redirect away from (e.g.: `example.com`, `myapp.io`, etc.).

* The subdomain you want to redirect to (e.g.: `app`, `www`, etc.).

* Access to the DNS configuration for the domain. Your DNS provider must support ALIAS records (also known as CNAME flattening). We support the following DNS providers in this tutorial: Amazon Route 53, CloudFlare, DNSimple. If your DNS provider does not support ALIAS records, then we encourage you to migrate your NS records to one that does.

* Access to one of the mailboxes used by AWS Certificate Manager to validate ownership of your domain. If you registered the domain yourself, that should be the case, but otherwise, review the [relevant AWS Certificate Manager documentation](http://docs.aws.amazon.com/acm/latest/userguide/gs-acm-validate.html) first.

* An AWS account.

After completing this tutorial, you will have an inexpensive highly-available redirect from your domain apex to your subdomain, which will require absolutely no maintenance going forward.

## Create the CloudFormation Stack

Navigate to [the CloudFormation Console](https://console.aws.amazon.com/cloudformation/home?region=us-east-1), and click "Create Stack".

Note that **you must create this stack in the** **`us-east-1`** **region**, but your redirect will be served globally with minimal latency via AWS CloudFront.

Choose "Specify an Amazon S3 template URL", and use the following template URL:

```url theme={null}
https://s3.amazonaws.com/www.aptible.com/assets/cloudformation-redirect.yaml
```

Click "Next", then:

* For the `Stack name`, choose any name you'll recognize in the future, e.g.: `redirect-example-com`.

* For the `Domain` parameter, input the domain you want to redirect away from.

* For the `Subdomain` parameter, use the subdomain. Don't include the domain itself there! For example, you want to redirect to `app.example.com`, then just input `app`.

* For the `ViewerBucketName` parameter, input any name you'll recognize in the future. You **cannot use dots** here. A name like `redirect-example-com` will work here too.

Then, hit "Next", and click through the following screen as well.

## Validate Domain Ownership

In order to set up the apex redirect to require no maintenance, the CloudFormation template we provide uses AWS Certificate Manager to automatically provision and renew a (free) certificate to serve the redirect from your domain apex to your subdomain.

To make this work, you'll need to validate with AWS that you own the domain you're using. So, once the CloudFormation stack enters the state `CREATE_IN_PROGRESS`, navigate to your mailbox, and look for an email from AWS to validate your domain ownership.

Once you receive it, read the instructions and click through to validate.

## Wait for a little while!

Wait for the CloudFormation stack to enter the state `CREATE_COMPLETE`.

This process will take about one hour, so sit back while CloudFormation does the work and come back once it's complete (but we'd suggest you stay around for the first 5 minutes or so in case an error shows up).

If, for some reason, the process fails, review the error in the stack's Events tab. This may be caused by choosing a bucket name that is already in use. Once you've identified the error, delete the stack, and start over again.

## Configure your DNS provider

Once CloudFormation is done working, you need to tie it all together by routing requests from your domain apex to CloudFormation.

To do this, you'll need to get the `DistributionHostname` provided by CloudFormation as an output for the stack. You can find it in CloudFormation under the Outputs tab for the stack after its state changes to `CREATE_COMPLETE`.

Once you have the hostname in hand, the instructions depend on your DNS provider.

If you're setting up a redirect for a domain that's already serving production traffic, now is a good time to check that the redirect works the way you expect.

To do so, use `curl` and verify that the following requests return a redirect to the right host (you should see a `Location` header in the response):

```sql theme={null}
# $DOMAIN should be set to your domain apex.
# $DISTRIBUTION should be set to the DistributionHostname.

# This should redirect to your subdomain over HTTP.
curl -v -H 'Host: $DOMAIN' 'http://$DISTRIBUTION'

# This should redirect to your subdomain over HTTPS.
curl -v -H 'Host: $DOMAIN' 'https://$DISTRIBUTION'
```

### If you use Amazon Route 53

Navigate to the Hosted Zone for your domain, then create a new record using the following options:

* Name: *Leave this blank* (this represents your domain apex).

* Type: A.

* Alias: Yes.

* Alias Target: the `DistributionHostname` you got from CloudFormation.

## If you use Cloudflare

Navigate to the CloudFlare dashboard for your domain, and create a new record with the following options:

* Type: CNAME.

* Name: Your domain.

* Domain Name: the `DistributionHostname` you got from CloudFormation.

Cloudflare will note that CNAME flattening will be used. That's OK, and expected.

## If you use DNSimple

Navigate to the DNSimple dashboard for your domain, and create a new record with the following options:

* Type: ALIAS

* Name: *Leave this blank* (this represents your domain apex).

* Alias For: the `DistributionHostname` you got from CloudFormation.


# Domain Apex ALIAS
Source: https://www.aptible.com/docs/how-to-guides/app-guides/use-domain-apex-with-endpoints/domain-apex-alias



Setting up an ALIAS record lets you serve your App from your [domain apex](/docs/how-to-guides/app-guides/use-domain-apex-with-endpoints/overview) directly, but there are significant tradeoffs involved in this approach:

First, this will break some Aptible functionality. Specifically, if you use an ALIAS record, Aptible will no longer be able to serve your [Maintenance Page](/docs/core-concepts/apps/connecting-to-apps/app-endpoints/https-endpoints/maintenance-page) from its backup error page server, [Brickwall](/docs/core-concepts/apps/connecting-to-apps/app-endpoints/https-endpoints/maintenance-page#brickwall). In fact, what happens exactly will depend on your DNS provider:

* Amazon Route 53: no error page will be served. Customers will most likely be presented with an error page from their browser indicating that the site is not working.

* Cloudflare, DNSimple: a generic Aptible error page will be served.

Second, depending on the provider, the ALIAS record may break in the future if Aptible needs to replace the underlying load balancer for your Endpoint. Specifically, this will be the case if your DNS provider is Amazon Route 53. We'll do our best to notify you if such a replacement needs to happen, but we cannot guarantee that you won't experience disruption during said replacement.

If, given these tradeoffs, you still want to set up an ALIAS record directly to your Aptible Endpoint, please contact [Aptible Support](/docs/how-to-guides/troubleshooting/aptible-support) for instructions.

If not, use this alternate approach: [Redirecting from your domain apex to a subdomain](/docs/how-to-guides/app-guides/use-domain-apex-with-endpoints/domain-apex-redirect).


# Domain Apex Redirect
Source: https://www.aptible.com/docs/how-to-guides/app-guides/use-domain-apex-with-endpoints/domain-apex-redirect



The general idea behind setting up a redirection is to sidestep your domain apex entirely and redirect your users transparently to a subdomain, from which you will be able to create a CNAME to an Aptible [Endpoint Hostname](/docs/core-concepts/apps/connecting-to-apps/app-endpoints/custom-domain#endpoint-hostname).

Most customers often choose to use a subdomain such as www or app for this purpose.

To set up a redirection from your domain apex to a subdomain, we strongly recommend using a combination of AWS S3, AWS CloudFront, and AWS Certificate Manager. Using these three services, you can set up a redirection that is easy to set up and requires absolutely no maintenance going forward.

To make things easier for you, Aptible provides detailed instructions to set this up, including a CloudFormation template that will automate all the heavy lifting for you.

To use this template, review the instructions here: [How do I set up an apex redirect using Amazon AWS](/docs/how-to-guides/app-guides/use-domain-apex-with-endpoints/aws-domain-apex-redirect).


# How to use Domain Apex with Endpoints
Source: https://www.aptible.com/docs/how-to-guides/app-guides/use-domain-apex-with-endpoints/overview



> 📘 This article assumes that you have created an [Endpoint](/docs/core-concepts/apps/connecting-to-apps/app-endpoints/overview) for your App, and that you have the [Endpoint Hostname](/docs/core-concepts/apps/connecting-to-apps/app-endpoints/custom-domain#endpoint-hostname) (the string that looks like `elb-XXX.aptible.in`) in hand.

> If you don't have that, start here: [How do I expose my web app on the Internet?](/docs/how-to-guides/app-guides/expose-web-app-to-internet).

As noted in the [Custom Domain](/docs/core-concepts/apps/connecting-to-apps/app-endpoints/custom-domain) documentation, Aptible requires that you create a CNAME from the domain of your choice to the Endpoint Hostname. Unfortunately, DNS does not allow the creation of CNAMEs for domain apexes (also known as "bare domains" or "root domains"). There are two options to work around this problem and we strongly recommend using the Redirect option.

## Redirect to a Subdomain

The general idea behind setting up a redirection is to sidestep your domain apex entirely and redirect your users transparently to a subdomain, from which you will be able to create a CNAME to an Aptible [Endpoint Hostname](/docs/core-concepts/apps/connecting-to-apps/app-endpoints/custom-domain#endpoint-hostname).

Most customers often choose to use a subdomain such as www or app for this purpose.

To set up a redirection from your domain apex to a subdomain, we strongly recommend using a combination of AWS S3, AWS CloudFront, and AWS Certificate Manager. Using these three services, you can set up a redirection that is easy to set up and requires absolutely no maintenance going forward.

To make things easier for you, Aptible provides detailed instructions to set this up, including a CloudFormation template that will automate all the heavy lifting for you.

To use this template, review the instructions here: [How do I set up an apex redirect using Amazon AWS](/docs/how-to-guides/app-guides/use-domain-apex-with-endpoints/aws-domain-apex-redirect).

## Use an ALIAS record

Setting up an ALIAS record lets you serve your App from your [domain apex](/docs/how-to-guides/app-guides/use-domain-apex-with-endpoints/overview) directly, but there are significant tradeoffs involved in this approach:

First, this will break some Aptible functionality. Specifically, if you use an ALIAS record, Aptible will no longer be able to serve your [Maintenance Page](/docs/core-concepts/apps/connecting-to-apps/app-endpoints/https-endpoints/maintenance-page) from its backup error page server, [Brickwall](/docs/core-concepts/apps/connecting-to-apps/app-endpoints/https-endpoints/maintenance-page#brickwall). In fact, what happens exactly will depend on your DNS provider:

* Amazon Route 53: no error page will be served. Customers will most likely be presented with an error page from their browser indicating that the site is not working.

* Cloudflare, DNSimple: a generic Aptible error page will be served.

Second, depending on the provider, the ALIAS record may break in the future if Aptible needs to replace the underlying load balancer for your Endpoint. Specifically, this will be the case if your DNS provider is Amazon Route 53. We'll do our best to notify you if such a replacement needs to happen, but we cannot guarantee that you won't experience disruption during said replacement.

If, given these tradeoffs, you still want to set up an ALIAS record directly to your Aptible Endpoint, please contact [Aptible Support](/docs/how-to-guides/troubleshooting/aptible-support) for instructions.

> 📘 Both approaches require a provider that supports ALIAS records (also known as CNAME flattening), such as Amazon Route 53, Cloudflare, or DNSimple.

> If your DNS records are hosted somewhere else, you will need to migrate to one of these providers or use a different solution (we strongly recommend against doing that).

> Note that you only need to update the NS records for your domain. You can keep using your existing provider as a registrar, and you don't need to transfer the domain over to one of the providers we recommend.

***

**Keep reading:**

* [Domain Apex ALIAS](/docs/how-to-guides/app-guides/use-domain-apex-with-endpoints/domain-apex-alias)
* [AWS Domain Apex Redirect](/docs/how-to-guides/app-guides/use-domain-apex-with-endpoints/aws-domain-apex-redirect)
* [Domain Apex Redirect](/docs/how-to-guides/app-guides/use-domain-apex-with-endpoints/domain-apex-redirect)


# Configuring Nginx proxies on Aptible
Source: https://www.aptible.com/docs/how-to-guides/app-guides/use-nginx-with-aptible-endpoints



Nginx is a popular choice for building custom reverse proxies on Aptible. When you deploy Nginx as an App on the platform, you are responsible for its configuration and maintenance.

This guide helps you avoid a common pitfall when configuring your Nginx app to route requests to Aptible [Endpoints](/docs/core-concepts/apps/connecting-to-apps/app-endpoints/overview) using a `proxy_pass` directive.

## The problem: DNS caching in Nginx

By default, Nginx caches the IP addresses of upstream servers indefinitely and ignores DNS TTLs. Aptible Endpoints use AWS load balancers, which periodically change IP addresses. This mismatch causes Nginx to eventually route traffic to stale IPs.

Avoid this configuration pattern:

```nginx theme={null}
location / {
    proxy_pass https://hostname-of-an-endpoint;
}
```

## The solution: Configure the resolver directive

Configure the `resolver` directive to dynamically resolve upstream servers. Though any public DNS server could be used here (such as Google or Cloudflare), we recommend using the AWS VPC DNS Resolver `169.254.169.253` with a short TTL to ensure Nginx resolves DNS regularly (in the example below we use 60 seconds).

```nginx theme={null}
resolver 169.254.169.253 valid=60s;
set $upstream_endpoint https://hostname-of-an-endpoint;

location / {
    proxy_pass $upstream_endpoint;
}
```

<Note>
  The AWS VPC DNS Resolver (`169.254.169.253`) has some reasonable capacity limits, metered in packets per second per network interface. In typical use, it is very unlikely for a typical deployment to reach this limit. In the rare case that you're seeing persistent DNS resolution issues while using the AWS VPC DNS Resolver, please reach out to the [Aptible Support team](/docs/how-to-guides/troubleshooting/aptible-support).
</Note>


# How to use S3 to accept file uploads
Source: https://www.aptible.com/docs/how-to-guides/app-guides/use-s3-to-accept-file-uploads

Learn how to connect your app to S3 to accept file uploads

## Overview

As noted in the [Container Lifecycle](/docs/core-concepts/architecture/containers/overview) documentation, [Containers](/docs/core-concepts/architecture/containers/overview) on Aptible are fundamentally ephemeral, and you should **never use the filesystem for long-term file or data storage**.

The best approach for storing files uploaded by your customers (or, more broadly speaking, any blob data generated by your app, such as PDFs, etc.) is to use a third-party object store, such as AWS S3.

You can store data in an Aptible [database](/docs/core-concepts/managed-databases/managing-databases/overview), but often at a performance cost.

## Using AWS S3 for PHI

> ❗️ If you are storing regulated or sensitive information, ensure you have the proper agreements with your storage provider. For example, you'll need to execute a BAA with AWS and use encryption (client-side or server-side) to store PHI in AWS S3.

For storing PHI on Amazon S3, you must get a separate BAA with Amazon Web Services. This BAA will require that you encrypt all data stored on S3. You have three options for implementing encryption, ranked from best to worst based on the combination of ease of implementation and security:

1. **Server-side encryption with customer-provided keys** ([SSE-C](https://docs.aws.amazon.com/AmazonS3/latest/dev/ServerSideEncryptionCustomerKeys.html)): You specify the key when uploading and downloading objects to/from S3. You are responsible for remembering the encryption key but don't have to choose or maintain an encryption library.

2. **Client-side encryption** ([CSE](https://docs.aws.amazon.com/AmazonS3/latest/dev/UsingClientSideEncryption.html)): This approach is the most challenging but also gives you complete control. You pick an encryption library and implement the encryption/decryption logic.

3. **Server-side encryption with Amazon-provided keys** ([SSE](https://docs.aws.amazon.com/AmazonS3/latest/dev/UsingServerSideEncryption.html)): This is the most straightforward approach but the least secure. You need only specify that encryption should occur on PUT, and you never need to keep track of encryption keys. The downside is that if any of your privileged AWS accounts (or access keys) are compromised, your S3 data may be compromised and unprotected by a secondary key.

There are two ways to serve S3 media files:

1. Generate a pre-signed URL so that the client can access them directly from S3 (note: this will not work if you're using client-side encryption)

2. Route all media requests through your app, fetch the S3 file within your app code, then re-serve it to the client.

The first approach is superior from a performance perspective. However, if these are PHI-sensitive media files, we recommend the second approach due to the control it gives you concerning audit logging, as you can more easily connect specific S3 file access to individual users in your system.


# Automate Database migrations
Source: https://www.aptible.com/docs/how-to-guides/database-guides/automate-database-migrations



Many app frameworks provide libraries for managing database migrations between different revisions of an app.

For example, Rails' ActiveRecord library allows users to define migration files and then run `bundle exec rake db:migrate` to execute them.

To automatically run migrations on each deploy to Aptible, you can use a [`before_release`](/docs/core-concepts/apps/deploying-apps/releases/aptible-yml#before-release) command.

To do so, add the following to your [`.aptible.yml`](/docs/core-concepts/apps/deploying-apps/releases/aptible-yml) file (adjust the command as needed depending on your framework):

```bash theme={null}
before_release:
  - bundle exec rake db:migrate
```

> ❗️ Don't break your App when running Database migrations! It's easy to forget that your App will be running when automated Database migrations execute, but it's important not to. For example, if your migration locks a table for 10 minutes (e.g., to create a new index synchronously), then that table is going to read-only for 10 minutes. If your App needs to write to this table to function, **it will be down**. Also, if your App is a web App, review the docs over here: [Concurrent Releases](/docs/core-concepts/apps/deploying-apps/releases/overview#concurrent-releases).

## Migration Scripts

If you need to run more complex migration scripts (e.g., with `if` branches, etc.), we recommend encapsulating this logic in a separate script:

```python theme={null}
#!/bin/sh
# This file lives at script/before_release.sh

if [ "$RAILS_ENV" == "staging" ]; then
  bundle exec rake db:[TASK]
else
  bundle exec rake db:[OTHER_TASK]
fi
```

> ❗️The script needs to be made executable. To do so, run `chmod script/before_release.sh`.

Your new `.aptible.yml` would read:

```bash theme={null}
before_release:
  - script/before_release.sh
```


# How to configure Aptible PostgreSQL Databases
Source: https://www.aptible.com/docs/how-to-guides/database-guides/configure-aptible-postgresql-databases

Learn how to configure PostgreSQL Databases on Aptible

## Overview

This guide will walk you through the steps of changing, applying, and checking settings, in addition to configuring access control, for an [Aptible PostgreSQL](/docs/core-concepts/managed-databases/supported-databases/postgresql) database.

## Changing Settings

As described in Aptible’s [PostgreSQL Configuration](/docs/core-concepts/managed-databases/supported-databases/postgresql#configuration) documentation, the [`ALTER SYSTEM`](https://www.postgresql.org/docs/current/sql-altersystem.html)command can be used to make persistent, global changes to [`pg_settings`](https://www.postgresql.org/docs/current/view-pg-settings.html).

* `ALTER SYSTEM SET` changes a setting to a specified value. For example, `ALTER SYSTEM SET max_connections = 500;`.

* `ALTER SYSTEM RESET` resets a setting to the default value set in [`postgresql.conf`](https://github.com/aptible/docker-postgresql/blob/master/templates/etc/postgresql/PG_VERSION/main/postgresql.conf.template) i.e. the Aptible default setting. For example, `ALTER SYSTEM RESET max_connections`.

## Applying Settings

Changes to settings are not necessarily applied immediately. The setting’s `context` determines when the change is applied. The current contexts for settings that can be changed with `ALTER SYSTEM` are:

* `postmaster` - Server settings that cannot be changed after the Database starts. Restarting the Database is required to apply these settings.

* `backend` and `superuser-backend` - Connection settings that cannot be changed after the connection is established. New connections will use the updated settings.

* `sighup` - Server settings that can be changed at runtime. The Database’s configuration must be reloaded in order to apply these settings.

* `user` and `superuser` - Session settings that can be changed with `SET` . New sessions will use the updated settings by default and reloading the configuration will apply it to all existing sessions that have not changed the setting.

Any time the Database container restarts including when it crashes or when the [`aptible db:reload`](/docs/reference/aptible-cli/cli-commands/cli-db-reload) or [`aptible db:restart`](/docs/reference/aptible-cli/cli-commands/cli-db-restart) CLI commands are run will apply any pending changes. `aptible db:reload` is recommended as it incurs the least amount of downtime. Restarting the Database is the only way to apply `postmaster` settings. It will also ensure that all `backend` and `superuser-backend` settings are being used by all open connections since restarting the Database will terminate all connections, forcing clients to establish new connections.

For settings that can be changed at runtime, the `pg_reload_conf` function (i.e. running `SELECT pg_reload_conf();`) will apply the changes to the Database and existing sessions. This is required to apply `sighup` settings without restarting the Database. `user` and `superuser` settings don’t require the configuration to be reloaded but, if it isn’t, the changes will only apply to new sessions so it’s recommended in order to ensure all sessions are using the same default configuration.

## Checking Setting Values and Contexts

### Show pg\_settings

The `pg_settings` view contains information on the current settings being used by the Database. The following query selects the relevant columns from `pg_settings` for a single setting:

```js theme={null}
SELECT name, setting, context, pending_restart
FROM pg_settings
WHERE name = 'max_connections';

```

Note that `setting` is the current value for the session and does not reflect changes that have not yet been applied. The `pending_restart` column indicates if a setting has been changed that cannot be applied until the Database is restarted. Running `SELECT pg_reload_conf();`, will update this column and if it’s `TRUE` (`t`) you know that the Database needs to be restarted.

### Show pending restarts

Using this, you can reload the config and then query if any settings have been changed that require the Database to be restarted.

```js theme={null}
SELECT name, setting, context, pending_restart
FROM pg_settings
WHERE pending_restart IS TRUE;

```

### Show non-default Settings:

Using this, you can show all non-default settings:

```js theme={null}
SELECT name, current_setting(name), source, sourcefile, sourceline
FROM pg_settings
WHERE(source <> 'default' OR name = 'server_version') 
AND name NOT IN('config_file', 'data_directory', 'hba_file', 'ident_file');
```

### Show all settings

Using this, you can show all non-default settings:

```js theme={null}
SHOW ALL;
```

## Configuring Access Control

The [`pg_hba.conf` file](https://www.postgresql.org/docs/current/auth-pg-hba-conf.html) (host-based authentication) controls where the PostgreSQL database can be accessed from and is traditionally the way you would restrict access. However, Aptible PostgreSQL Databases configure [`pg_hba.conf`](https://github.com/aptible/docker-postgresql/blob/master/templates/etc/postgresql/PG_VERSION/main/pg_hba.conf.template) to allow access from any source and it cannot be modified. Instead, access is controlled by the Aptible infrastructure. By default, Databases are only accessible from within the Stack that they run on but they can be exposed to external sources via [Database Endpoints](/docs/core-concepts/managed-databases/connecting-databases/database-endpoints) or [Network Integrations](/docs/core-concepts/integrations/network-integrations).


# How to connect Fivetran with your Aptible databases
Source: https://www.aptible.com/docs/how-to-guides/database-guides/connect-fivetran-with-aptible-db

Learn how to connect Fivetran with your Aptible Databases

## Overview

[Fivetran](https://www.fivetran.com/) is a cloud-based platform that automates data movement, allowing easy extraction, loading, and transformation of data between various sources and destinations. Fivetran is compatible with Aptible Postgres and MySQL databases.

## Connecting with PostgreSQL Databases

> ⚠️ Prerequisites: A Fivetran account with the role to Create Destinations

To connect your existing Aptible [PostgreSQL](/docs/core-concepts/managed-databases/supported-databases/postgresql) Database to Fivetran:

**Step 1: Configure Fivetran**

Follow Fivetran’s [General PostgreSQL Guide](https://fivetran.com/docs/databases/postgresql/setup-guide), noting the following:

* The only supported “Connection method” is to Connect Directly

* `pgoutput` is the preferred method. All PostgreSQL databases version 10+ have this as the default logical replication plugin.

* The `wal_level` and `max_replication_slots` settings will already be present on your Aptible PostgreSQL database

  * Note: The default `max_replication_slots` is 10. You may need to increase this if you have many Aptible replicas or 3rd party replication using the allotted replication slots.

* The step to add a record to `pg_hba.conf` file can be skipped, as the settings Aptible sets for you are sufficient to allow a connection/authentication.

* Aptible PostgreSQL databases use the default value for `wal_sender_timeout` , so you’ll likely have to run `ALTER SYSTEM SET wal_sender_timeout 0;` or something similar, see related guide: [How to configure Aptible PostgreSQL Databases](/docs/how-to-guides/database-guides/configure-aptible-postgresql-databases)

**Step 2: Expose your database to Fivetram**

You’ll need to expose the PostgreSQL Database to your Fivetran instance:

* If you're running it as an Aptible App in the same Stack then it can access it by default.

* Otherwise, create a [Database Endpoint](/docs/core-concepts/managed-databases/connecting-databases/database-endpoints). Be sure to only allow [Fivetran's IP addresses](https://fivetran.com/docs/getting-started/ips) to connect!

## Connecting with MySQL Databases

> ⚠️ Prerequisites: A Fivetran account with the role to Create Destinations

To connect your existing Aptible [MySQL](/docs/core-concepts/managed-databases/supported-databases/mysql) Database to Fivetran:

**Step 1: Configure Fivetran** Follow Fivetran’s [General MySQL Guide](https://fivetran.com/docs/destinations/mysql/setup-guide), noting the following:

* The only supported “Connection method” is to Connect Directly

**Step 2: Expose your database to Fivetram**

You’ll need to expose the PostgreSQL Database to your Fivetran instance:

* If you're running it as an Aptible App in the same Stack then it can access it by default.

* Otherwise, create a [Database Endpoint](/docs/core-concepts/managed-databases/connecting-databases/database-endpoints). Be sure to only allow [Fivetran's IP addresses](https://fivetran.com/docs/getting-started/ips) to connect!

## Troubleshooting

* Fivetran replication queries can return a large amount of data per query. Fivetran support can tune down page size per query to smaller sizes, and this has resulted in positive results as a troubleshooting step.

* Very large Text / BLOB columns can have a potential impact on the Fivetran replication process. Customers have had success unblocking Fivetran replication by removing large Text / BLOB columns from the target Fivetran schema.


# Dump and restore MySQL
Source: https://www.aptible.com/docs/how-to-guides/database-guides/dump-restore-mysql



The goal of this guide is to dump the data from one MySQL [Database](/docs/core-concepts/managed-databases/managing-databases/overview) and restore it to another. This is generally done to upgrade to a new MySQL version but can be used in any situation where data needs to be migrated to a new Database instance.

> 📘 MySQL only supports upgrade between General Availability releases, so upgrading multiple versions (i.e. 5.6 => 8.0) requires going through the upgrade process multiple times.

## Preparation

#### Step 0: Install the necessary tools

Install the [Aptible CLI](/docs/reference/aptible-cli/cli-commands/overview) and [MySQL](https://dev.mysql.com/doc/refman/5.7/en/installing.html). This guide uses the `mysqldump` and `mysql` client tools.

#### Step 1: Workspace

The amount of time it takes to dump and restore a Database is directly related to the size of the Database and network bandwidth. If the Database being dumped is small (\< 10 GB) and bandwidth is decent, then dumping locally is usually fine. Otherwise, consider dumping and restoring from a server with more bandwidth, such as an AWS EC2 Instance.

Another thing to consider is available disk space. There should be at least as much space locally available as the Database is currently taking up on disk. See the Database's [metrics](/docs/core-concepts/observability/metrics/overview) to determine the current amount of space it's taking up. If there isn't enough space locally, this would be another good indicator to dump and restore from a server with a large enough disk.

All of the following instructions should be completed on the selected machine.

#### Step 2: Test the table definitions

If data is being transferred to a Database running a different MySQL version than the original, first check that the table definitions can be restored on the desired version by following the [How](/docs/how-to-guides/database-guides/test-upgrade-incompatibiltiies) [to use mysqldump to test for upgrade incompatibilities](/docs/how-to-guides/database-guides/test-upgrade-incompatibiltiies) guide.

If the same MySQL version is being used, this is not necessary.

#### Step 3: Test the upgrade

It's recommended to test the upgrade before performing it in production. The easiest way to do this is to restore the latest backup of the Database and perform the upgrade against the restored Database. The restored Database should have the same container size as the production Database.

Example:

```sql theme={null}
aptible backup:restore 1234 --handle upgrade-test --container-size 4096
```

> 📘 If you're performing the test to get an estimate of how much downtime is required to perform the upgrade, you'll need to dump the restored Database twice in order to get an accurate time estimate. The first time will ensure that all of the backup data has been synced to the disk. The second backup will take approximately the same amount of time as the production dump.

#### Step 4: Configuration

Collect information on the Database you'd like to test and store it in the following environment variables for use later in the guide:

* `SOURCE_HANDLE` - The handle (i.e., name) of the Database.

* `SOURCE_ENVIRONMENT` - The handle of the environment the Database belongs to.

Example:

```sql theme={null}
SOURCE_HANDLE='source-db'
SOURCE_ENVIRONMENT='test-environment'
```

Collect information on the target Database and store it in the following environment variables:

* `TARGET_HANDLE` - The handle (i.e., name) for the Database.

* `TARGET_VERSION` - The target MySQL version. Run `aptible db:versions` to see a full list of options. This must be within one General Availability version of the source Database.

* `TARGET_ENVIRONMENT` - The handle of the environment to create the Database in.

Example:

```sql theme={null}
TARGET_HANDLE='upgrade-test'
TARGET_VERSION='8.0'
TARGET_ENVIRONMENT='test-environment'
```

#### Step 5: Create the target Database

Create a new Database running the desired version. Assuming the environment variables above are set, this command can be copied and pasted as-is to create the Database.

```sql theme={null}
aptible db:create "$TARGET_HANDLE" \
  --type mysql \
  --version "$TARGET_VERSION" \
  --environment "$TARGET_ENVIRONMENT"
```

## Execution

#### Step 1: Scale Services down

Scale all [Services](/docs/core-concepts/apps/deploying-apps/services) that use the Database down to zero Containers. It's usually easiest to prepare a script that scales all Services down and another that scales them back up to their current values once the upgrade has been completed. Current Container counts can be found in the [Aptible Dashboard](https://app.aptible.com) or by running [`APTIBLE_OUTPUT_FORMAT=json aptible apps`](/docs/reference/aptible-cli/cli-commands/cli-apps).

Example:

```sql theme={null}
aptible apps:scale --app my-app cmd --container-count 0
```

While this step is not strictly required, it ensures that the Services don't write to the Database during the upgrade and that its [HTTP(S) Endpoints](/docs/core-concepts/apps/connecting-to-apps/app-endpoints/https-endpoints/overview) will show the App's [Maintenance Page](/docs/core-concepts/apps/connecting-to-apps/app-endpoints/https-endpoints/maintenance-page) if anyone tries to access them.

#### Step 2: Dump the data

In a terminal, create a [Database Tunnel](/docs/core-concepts/managed-databases/connecting-databases/database-tunnels) to the source Database using the Aptible CLI.

```sql theme={null}
aptible db:tunnel "$SOURCE_HANDLE" --environment "$SOURCE_ENVIRONMENT" --port 5432
```

The tunnel will block the current terminal until it's stopped. In another terminal, collect the tunnel's [Database Credentials](/docs/core-concepts/managed-databases/connecting-databases/database-credentials), which is printed by [`aptible db:tunnel`](/docs/reference/aptible-cli/cli-commands/cli-db-tunnel). Then dump the database and database object definitions into a file. `dump.sql` in this case.

```sql theme={null}
MYSQL_PWD="$PASSWORD" mysqldump  --user root --host localhost.aptible.in --port 5432 --all-databases --routines --events  > dump.sql
```

The following error may come up when dumping:

```sql theme={null}
Unknown table 'COLUMN_STATISTICS' in information_schema (1109)
```

This is due to a new flag that is enabled by default in `mysqldump 8`. You can disable this flag and resolve the error by adding `--column-statistics=0` to the above command.

You now have a copy of your Database's database object definitions in `dump.sql`! The Database Tunnel can be closed by following the instructions that `aptible db:tunnel` printed when the tunnel started.

#### Step 3: Restore the data

Create a [Database Tunnel](/docs/core-concepts/managed-databases/connecting-databases/database-tunnels) to the target Database using the Aptible CLI.

```sql theme={null}
aptible db:tunnel "$TARGET_HANDLE" --environment "$TARGET_ENVIRONMENT" --port 5432
```

Again, the tunnel will block the current terminal until it's stopped. In another terminal, apply the table definitions to the target Database.

```sql theme={null}
MYSQL_PWD="$PASSWORD" mysql --user root --host localhost.aptible.in --port 5432 < dump.sql
```

> 📘 If there are any errors, they will need to be addressed in order to be able to upgrade the source Database to the desired version. Consult the [MySQL Documentation](https://dev.mysql.com/doc/) for details about the errors you encounter.

#### Step 4: Deprovision target Database

Once you've updated the source Database, you can try the dump again by deprovisioning the target Database and starting from the [Create the target Database](/docs/how-to-guides/database-guides/dump-restore-mysql#create-the-target-database) step.

```sql theme={null}
aptible db:deprovision "$TARGET_HANDLE" --environment "$TARGET_ENVIRONMENT"
```

#### Step 5: Delete Final Backups (Optional)

If the `$TARGET_ENVIRONMENT` is configured to [retain final Database Backups](/docs/core-concepts/managed-databases/managing-databases/database-backups#retention-and-disposal), which is enabled by default, you may want to delete the final backup for the target Database.

You can obtain a list of final backups by running the following:

```sql theme={null}
aptible backup:orphaned --environment "$TARGET_ENVIRONMENT"
```

Then, delete the backup(s) by ID using the [`aptible backup:purge`](/docs/reference/aptible-cli/cli-commands/cli-backup-purge) command.

#### Step 6: Update Services

Once the upgrade is complete, any Services that use the existing Database need to be updated to use the upgraded target Database. Assuming you're supplying the [Database Credentials](/docs/core-concepts/managed-databases/connecting-databases/database-credentials) through the App's [Configuration](/docs/core-concepts/apps/deploying-apps/configuration), this can usually be easily done with the [`aptible config:set`](/docs/reference/aptible-cli/cli-commands/cli-config-set) command.

Example:

```sql theme={null}
aptible config:set --app my-app DB_URL='mysql://aptible:pa$word@db-stack-1234.aptible.in:5432/db'
```

#### Step 7: Scale Services back up

If Services were scaled down before performing the upgrade, they need to be scaled back up afterward. This would be the time to run the scale-up script that was mentioned in [Scale Services down](/docs/how-to-guides/database-guides/dump-restore-mysql#scale-services-down)

Example:

```sql theme={null}
aptible apps:scale --app my-app cmd --container-count 2
```

## Cleanup

Once the original Database is no longer necessary, it should be deprovisioned, or it will continue to incur costs. Note that this will delete all automated Backups. If you'd like to retain the Backups, contact [Aptible Support](/docs/how-to-guides/troubleshooting/aptible-support) to update them.

```sql theme={null}
aptible db:deprovision "$SOURCE_HANDLE" --environment "$SOURCE_ENVIRONMENT"
```


# Dump and restore PostgreSQL
Source: https://www.aptible.com/docs/how-to-guides/database-guides/dump-restore-postgresql



The goal of this guide is to dump the schema and data from one PostgreSQL [Database](/docs/core-concepts/managed-databases/managing-databases/overview) and restore it to another. This is generally done to upgrade to a new PostgreSQL version but can be used in any situation where data needs to be migrated to a new Database instance.

## Preparation

## Workspace

The amount of time it takes to dump and restore a Database is directly related to the size of the Database and network bandwidth. If the Database being dumped is small (\< 10 GB) and bandwidth is decent, then dumping locally is usually fine. Otherwise, consider dumping and restoring from a server with more bandwidth, such as an AWS EC2 Instance.

Another thing to consider is available disk space. There should be at least as much space locally available as the Database is currently taking up on disk. See the Database's [metrics](/docs/core-concepts/observability/metrics/overview) to determine the current amount of space it's taking up. If there isn't enough space locally, this would be another good indicator to dump and restore from a server with a large enough disk.

All of the following instructions should be completed on the selected machine.

## Test the schema

If data is being transferred to a Database running a different PostgreSQL version than the original, first check that the schema can be restored on the desired version by following the [How to test a PostgreSQL Database's schema on a new version](/docs/how-to-guides/database-guides/test-schema-new-version) guide.

If the same PostgreSQL version is being used, this is not necessary.

## Test the upgrade

Testing the schema should catch most issues but it's also recommended to test the upgrade before performing it in production. The easiest way to do this is to restore the latest backup of the Database and performing the upgrade against the restored Database. The restored Database should have the same container size as the production Database.

Example:

```sql theme={null}
aptible backup:restore 1234 --handle upgrade-test --container-size 4096
```

Note that if you're performing the test to get an estimate of how much downtime is required to perform the upgrade, you'll need to dump the restored Database twice in order to get an accurate time estimate. The first time will ensure that all of the backup data has been synced to the disk. The second backup will take approximately the same amount of time as the production dump.
Tools
Install the [Aptible CLI](/docs/reference/aptible-cli/cli-commands/overview) and [PostgreSQL Client Tools](https://www.postgresql.org/download/). This guide uses the `pg_dumpall` and `psql` client tools.

## Configuration

Collect information on the Database you'd like to upgrade and store it in the following environment variables for use later in the guide:

* `SOURCE_HANDLE` - The handle (i.e. name) of the Database.

* `SOURCE_ENVIRONMENT` - The handle of the environment the Database belongs to.

Example:

```sql theme={null}
SOURCE_HANDLE='source-db'
SOURCE_ENVIRONMENT='test-environment'
```

Collect information on the target Database and store it in in the following environment variables:

* `TARGET_HANDLE` - The handle (i.e. name) for the Database.

* `TARGET_VERSION` - The target PostgreSQL version. Run `aptible db:versions` to see a full list of options.

* `TARGET_ENVIRONMENT` - The handle of the environment to create the Database in.

* `TARGET_DISK_SIZE` - The size of the target Database's disk in GB. This must be at least be as large as the current Database takes up on disk but can be smaller than its overall disk size.

* `TARGET_CONTAINER_SIZE` (Optional) - The size of the target Database's container in MB. Having more memory and CPU available speeds up the dump and restore process, up to a certain point. See the [Database Scaling](/docs/core-concepts/scaling/database-scaling#ram-scaling) documentation for a full list of supported container sizes.

Example:

```sql theme={null}
TARGET_HANDLE='dump-test'
TARGET_VERSION='14'
TARGET_ENVIRONMENT='test-environment'
TARGET_DISK_SIZE=100
TARGET_CONTAINER_SIZE=4096
```

## Create the target Database

Create a new Database running the desired version. Assuming the environment variables above are set, this command can be copied and pasted as-is to create the Database.

```sql theme={null}
aptible db:create "$TARGET_HANDLE" \
  --type postgresql \
  --version "$TARGET_VERSION" \
  --environment "$TARGET_ENVIRONMENT" \
  --disk-size "$TARGET_DISK_SIZE" \
  --container-size "${TARGET_CONTAINER_SIZE:-4096}"
```

## Execution

## Scale Services down

Scale all [Services](/docs/core-concepts/apps/deploying-apps/services) that use the Database down to zero containers. It's usually easiest to prepare a script that scales all Services down and another that scales them back up to their current values once the upgrade has been complete. Current container counts can be found in the [Aptible Dashboard](https://app.aptible.com) or by running [`APTIBLE_OUTPUT_FORMAT=json aptible apps`](/docs/reference/aptible-cli/cli-commands/cli-apps).

Example scale command:

```sql theme={null}
aptible apps:scale --app my-app cmd --container-count 0
```

While this step is not strictly required, it ensures that the Services don't write to the Database during the upgrade and that its [HTTP(S) Endpoints](/docs/core-concepts/apps/connecting-to-apps/app-endpoints/https-endpoints/overview) will show the App's [Maintenance Page](/docs/core-concepts/apps/connecting-to-apps/app-endpoints/https-endpoints/maintenance-page) if anyone tries to access them.

## Dump the data

In a separate terminal, create a [Database Tunnel](/docs/core-concepts/managed-databases/connecting-databases/database-tunnels) to the source Database using the Aptible CLI.

```sql theme={null}
aptible db:tunnel "$SOURCE_HANDLE" --environment "$SOURCE_ENVIRONMENT"
```

The tunnel will block the current terminal until it's stopped. Collect the tunnel's information, which is printed by [`aptible db:tunnel`](/docs/reference/aptible-cli/cli-commands/cli-db-tunnel), and store it in the following environment variables in the original terminal:

* `SOURCE_URL` - The full URL of the Database tunnel.

* `SOURCE_PASSWORD` - The Database's password.

Example:

```sql theme={null}
SOURCE_URL='postgresql://aptible:pa$word@localhost.aptible.in:5432/db'
SOURCE_PASSWORD='pa$word'
```

Dump the data into a file. `dump.sql` in this case.

```sql theme={null}
PGPASSWORD="$SOURCE_PASSWORD" pg_dumpall -d "$SOURCE_URL" --no-password \
  | grep -E -i -v 'ALTER ROLE aptible .*PASSWORD' > dump.sql
```

The output of `pg_dumpall` is piped into `grep` in order to remove any SQL commands that may change the default `aptible` user's password. If these commands were to run on the target Database, it would be updated to match the source Database. This would result in the target Database's password no longer matching what's displayed in the [Aptible Dashboard](https://app.aptible.com) or printed by commands like [`aptible db:url`](/docs/reference/aptible-cli/cli-commands/cli-db-url) or [`aptible db:tunnel`](/docs/reference/aptible-cli/cli-commands/cli-db-tunnel) which could cause problems down the road.

You now have a copy of your Database's schema and data in `dump.sql`! The Database Tunnel can be closed by following the instructions that `aptible db:tunnel` printed when the tunnel started.

## Restore the data

In a separate terminal, create a [Database Tunnel](/docs/core-concepts/managed-databases/connecting-databases/database-tunnels) to the target Database using the Aptible CLI.

```sql theme={null}
aptible db:tunnel "$TARGET_HANDLE" --environment "$TARGET_ENVIRONMENT"
```

Again, the tunnel will block the current terminal until it's stopped. Collect the tunnel's full URL, which is printed by [`aptible db:tunnel`](/docs/reference/aptible-cli/cli-commands/cli-db-tunnel), and store it in the `TARGET_URL` environment variable in the original terminal.

Example:

```sql theme={null}
TARGET_URL='postgresql://aptible:passw0rd@localhost.aptible.in:5432/db'
```

Apply the data to the target Database.

```sql theme={null}
psql $TARGET_URL -f dump.sql > /dev/null
```

The output of `psql` can be noisy depending on the size of the source Database. In order to reduce the noise, the output is redirected to `/dev/null` so that only error messages are displayed.

The following errors may come up when restoring the Database:

```sql theme={null}
ERROR:  role "aptible" already exists
ERROR:  role "postgres" already exists
ERROR:  database "db" already exists
```

These errors are expected because Aptible creates these resources on all PostgreSQL Databases when they are created. The errors are a result of the dump attempting to re-create the existing resources. If these are the only errors, the upgrade was successful!

### Errors

If there are additional errors, they will need to be addressed in order to be able to upgrade the source Database to the desired version. Consult the [PostgreSQL Documentation](https://www.postgresql.org/docs/) for details about the errors you encounter.

Once you've updated the source Database, you can try the dump again by deprovisioning the target Database and starting from the [Create the target Database](/docs/how-to-guides/database-guides/dump-restore-postgresql#create-the-target-database) step.

```sql theme={null}
aptible db:deprovision "$TARGET_HANDLE" --environment "$TARGET_ENVIRONMENT"
```

If the `$TARGET_ENVIRONMENT` is configured to [retain final Database Backups](/docs/core-concepts/managed-databases/managing-databases/database-backups#retention-and-disposal), which is enabled by default, you may want to delete the final backup for the target Database.

You can obtain a list of final backups by running:

```sql theme={null}
aptible backup:orphaned --environment "$TARGET_ENVIRONMENT"
```

Then, delete the backup(s) by ID using the [`aptible backup:purge`](/docs/reference/aptible-cli/cli-commands/cli-backup-purge) command.

## Update Services

Once the upgrade is complete, any Services that use the existing Database need to be updated to use the upgraded target Database. Assuming you're supplying the [Database Credentials](/docs/core-concepts/managed-databases/connecting-databases/database-credentials) through the App's [Configuration](/docs/core-concepts/apps/deploying-apps/configuration), this can usually be easily done with the [`aptible config:set`](/docs/reference/aptible-cli/cli-commands/cli-config-set) command.

Example config command:

```sql theme={null}
aptible config:set --app my-app DB_URL='postgresql://user:passw0rd@db-stack-1234.aptible.in:5432/db'
```

## Scale Services back up

If Services were scaled down before performing the upgrade, they need to be scaled back up afterward. This would be the time to run the scale-up script that was mentioned in [Scale Services down](/docs/how-to-guides/database-guides/dump-restore-postgresql#scale-services-down)

Example:

```sql theme={null}
aptible apps:scale --app my-app cmd --container-count 2
```

## Cleanup

## Vacuum and Analyze

Vacuuming the target Database after upgrading reclaims space occupied by dead tuples and analyzing the tables collects information on the table's contents in order to improve query performance.

```sql theme={null}
psql "$TARGET_URL" --tuples-only --no-align --command \
  'SELECT datname FROM pg_database WHERE datistemplate IS FALSE' |

while IFS= read -r db; do
  psql "$TARGET_URL" << EOF
    \connect "$db"

    VACUUM ANALYZE;
EOF
done
```

## Deprovision

Once the original Database is no longer necessary, it should be deprovisioned or it will continue to incur costs. Note that this will delete all automated Backups. If you'd like to retain the Backups, contact [Aptible Support](/docs/how-to-guides/troubleshooting/aptible-support) to update them.

```sql theme={null}
aptible db:deprovision "$SOURCE_HANDLE" --environment "$SOURCE_ENVIRONMENT"
```


# How to scale databases
Source: https://www.aptible.com/docs/how-to-guides/database-guides/how-to-scale-databases

Learn how to scale databases on Aptible

## Overview

Aptible [Databases](/docs/core-concepts/managed-databases/managing-databases/overview) can be manually scaled with minimal downtime (typically less than 1 minute). There are several elements of databases that can be scaled, such as CPU, RAM, IOPS, and throughput. See [Database Scaling](/docs/core-concepts/scaling/database-scaling) for more information.

## Using the Aptible Dashboard

Databases can be scaled within the Aptible Dashboard by:

* Navigating to the Environment in which your Database lives in

* Selecting the **Databases** tab

* Selecting the respective Database

* Selecting **Scale**

<img alt="" />

## Using the CLI

Databases can be scaled via the Aptible CLI using the [`aptible db:restart`](/docs/reference/aptible-cli/cli-commands/cli-db-restart) command.

## Using Terraform

Databases can be programmatically scaled using the Aptible [Terraform Provider](https://registry.terraform.io/providers/aptible/aptible/latest/docs) using the `terraform_aptible_database` resource:

```js theme={null}
 resource "aptible_database" "DATABASE" {
    env_id = ENVIRONMENT_ID
    handle = "DATABASE_HANDLE"
    database_type = "redis"
    container_size = 512
    disk_size = 10
}
```


# All Database Guides
Source: https://www.aptible.com/docs/how-to-guides/database-guides/overview

Explore guides for deploying and managing databases on Aptible

* [How to configure Aptible PostgreSQL Databases](/docs/how-to-guides/database-guides/configure-aptible-postgresql-databases)

* [How to connect Fivetran with your Aptible databases](/docs/how-to-guides/database-guides/connect-fivetran-with-aptible-db)

* [How to replicate PostgreSQL to BigQuery with Datastream](/docs/how-to-guides/database-guides/replicate-postgresql-to-bigquery-datastream)

* [How to scale databases](/docs/how-to-guides/database-guides/how-to-scale-databases)

* [Automate Database migrations](/docs/how-to-guides/database-guides/automate-database-migrations)

* [Upgrade PostgreSQL with logical replication](/docs/how-to-guides/database-guides/upgrade-postgresql)

* [Dump and restore PostgreSQL](/docs/how-to-guides/database-guides/dump-restore-postgresql)

* [Test a PostgreSQL Database's schema on a new version](/docs/how-to-guides/database-guides/test-schema-new-version)

* [Dump and restore MySQL](/docs/how-to-guides/database-guides/dump-restore-mysql)

* [Use mysqldump to test for upgrade incompatibilities](/docs/how-to-guides/database-guides/test-upgrade-incompatibiltiies)

* [Upgrade MongoDB](/docs/how-to-guides/database-guides/upgrade-mongodb)

* [Upgrade Redis](/docs/how-to-guides/database-guides/upgrade-redis)

* [Deploy PgBouncer](/docs/how-to-guides/database-guides/pgbouncer-connection-pooling)


# Deploying PgBouncer on Aptible
Source: https://www.aptible.com/docs/how-to-guides/database-guides/pgbouncer-connection-pooling

How to deploy PgBouncer on Aptible

PgBouncer is a lightweight connection pooler for PostgreSQL which helps reduce resource usage and overhead by managing database connections.
This guide provides a overview on how you can get started with PgBouncer on Aptible and [deploying via Git](https://www.aptible.com/docs/core-concepts/apps/deploying-apps/image/deploying-with-git/overview#deploying-with-git).

<Steps>
  <Step title="Setting Up PgBouncer">
    <Accordion title="Gather Database Variables">
      To successfully use and configure PgBouncer, you'll need to have a PostgreSQL database you want to pool connections for. From that database, you'll need to know the following:

      * PostgreSQL username
      * PostgreSQL password
      * PostgreSQL host
      * PostgreSQL port
      * PostgreSQL database name
        These values can be retrieved from the [Database Credentials](https://www.aptible.com/docs/core-concepts/managed-databases/connecting-databases/database-credentials#overview) in the UI, and will be used to set configuration variables later in the guide.
        For example:

      ```
      If the Database Credentials were
      postgresql://aptible:very_secure_password@db-aptible-docs-example-1000.aptible.in:4000/db

      PostgreSQL username      = 'aptible'
      PostgreSQL password      = 'very_secure_password'
      PostgreSQL host          = 'db-aptible-docs-example-1000.aptible.in'
      PostgreSQL port          = 4000
      PostgreSQL database name = 'db'
      ```
    </Accordion>

    <Accordion title="Create your PgBouncer Application">
      Through the UI or CLI, create the PgBouncer application, and set a few variables:

      ```
        aptible apps:create pgbouncer
        aptible config:set --app pgbouncer \
        POSTGRESQL_USERNAME='aptible' \
        POSTGRESQL_PASSWORD=$PASSWORD \
        POSTGRESQL_DATABASE='db' \
        POSTGRESQL_HOST='$DB_HOSTNAME' \
        POSTGRESQL_PORT='$DB_PORT' \
        PGBOUNCER_DATABASE='db' \
        PGBOUNCER_SERVER_TLS_SSLMODE='require' \
        PGBOUNCER_AUTH_USER='aptible' \
        PGBOUNCER_AUTH_QUERY='SELECT uname, phash FROM user_lookup($1)' \
        IDLE_TIMEOUT=2400 \
        PGBOUNCER_CLIENT_TLS_SSLMODE='require' \
        PGBOUNCER_CLIENT_TLS_KEY_FILE='/opt/bitnami/pgbouncer/certs/pgbouncer.key' \
        PGBOUNCER_CLIENT_TLS_CERT_FILE='/opt/bitnami/pgbouncer/certs/pgbouncer.crt' \
      ```

      Note that you'll need to fill out a few variables with the Database Credentials you previously gathered. We're also assuming the certificate and key you're using to authenticate will be saved as `pgbouncer.crt` and `pgbouncer.key`.
    </Accordion>

    <Accordion title="Generate a Certificate and Key for SSL Authentication">
      Since databases on Aptible require SSL, you'll also need to provide an authentication certificate and key. These can be self-signed and created using `openssl`.

      1. Generate a Root Certificate and Key

      ```
      openssl req -x509 \ 
              -sha256 -days 365 \
              -nodes \
              -newkey rsa:2048 \
              -subj "/CN=app-$APP_ID.on-aptible.com/C=US/L=San Fransisco" \
              -keyout rootCA.key -out rootCA.crt
      ```

      This creates a rootCA.key and rootCA.crt in your current directory. `-subj "/CN=app-$APP_ID.on-aptible.com/C=US/L=San Francisco"` is modifiable — notably, the Common Name, `/CN`, should match the TCP endpoint you've created for the pgbouncer App.
      If you're using a default endpoint, you can fill in \$APP\_ID with your Application's ID.

      2. Using the Root Certificate and key, create the authentication certificate and private key:

      ```
      openssl genrsa -out pgbouncer.key 2048
      openssl req -new -key pgbouncer.key -out pgbouncer.csr
      openssl x509 -req \
            -in pgbouncer.csr \
            -CA rootCA.crt -CAkey rootCA.key \
            -CAcreateserial -out pgbouncer.crt \
            -days 365 \
            -sha256
      ```
    </Accordion>
  </Step>

  <Step title="Create the Dockerfile">
    For a basic implementation, the Dockerfile is quite short:

    ```
    FROM bitnami/pgbouncer:latest
    COPY pgbouncer.key /opt/bitnami/pgbouncer/certs/pgbouncer.key
    COPY pgbouncer.crt /opt/bitnami/pgbouncer/certs/pgbouncer.crt
    ```

    We're using the PgBouncer image as a base, and then copying a certificate-key pair for TLS authentication to where PgBouncer expects them to be.
    This means that your git repository needs to contain three files: the Dockerfile, `pgbouncer.key`, and `pgbouncer.crt`.
  </Step>

  <Step title="Deploy using Git Push">
    Now you're ready to deploy. Since we're working from a Dockerfile, follow the steps in [Deploying with Git](https://www.aptible.com/docs/core-concepts/apps/deploying-apps/image/deploying-with-git/overview) to push your repository to your app's Git Remote to trigger a deploy.
  </Step>

  <Step title="Make an Endpoint for PgBouncer">
    This is commonly done by creating a TCP endpoint.

    ```
    aptible endpoints:tcp:create --app pgbouncer cmd --internal
    ```

    Instead of connecting to your database directly, you should configure your resources to connect to PgBouncer using the TCP endpoint.
  </Step>

  <Step title="Celebrate!">
    At this point, PgBouncer should be deployed. If you run into any issues, or have any questions, don't hesitate to reach out to [Aptible Support](https://app.aptible.com/support)
  </Step>
</Steps>


# Replicate PostgreSQL to BigQuery with Datastream
Source: https://www.aptible.com/docs/how-to-guides/database-guides/replicate-postgresql-to-bigquery-datastream

Configure Google Datastream to replicate changes from an Aptible PostgreSQL database to BigQuery.

This guide shows how to build a Change Data Capture (CDC) pipeline from an Aptible PostgreSQL Database to Google BigQuery using Google Datastream.

```text theme={null}
Aptible PostgreSQL -> Aptible Database Endpoint -> Google Datastream -> BigQuery
```

The Datastream connection uses a Database Endpoint with IP filtering and TLS certificate verification. PostgreSQL changes are read from the write-ahead log (WAL) using the `pgoutput` logical replication plugin.

## Prerequisites

* Administrator access to the Aptible Environment
* The [Aptible CLI](/docs/reference/aptible-cli/overview)
* A Google Cloud project with billing enabled
* The Datastream API and BigQuery API enabled in Google Cloud
* A PostgreSQL Database on Aptible

## Step 1: Configure Aptible Network Access

Create a [Database Endpoint](/docs/core-concepts/managed-databases/connecting-databases/database-endpoints) so Datastream can connect to your Database.

<Steps>
  <Step title="Create a Database Endpoint">
    In the Aptible Dashboard, navigate to the Database, open the **Endpoints** tab, and create a TCP Endpoint. Keep the Endpoint host and port available for the Google Datastream setup.
  </Step>

  <Step title="Get Google Datastream IP addresses">
    In Google Cloud, navigate to **Datastream** > **Connection Profiles** > **Create Profile**. Select PostgreSQL, choose the region where the stream will run, select **IP allowlisting** as the connectivity method, and copy the static IP addresses Google provides.
  </Step>

  <Step title="Allowlist Google IP addresses">
    Return to the Aptible Database Endpoint and add the Google Datastream static IP addresses to the Endpoint IP allowlist.
  </Step>
</Steps>

<Warning>
  Enable IP filtering on the Database Endpoint. Without IP filtering, the Database Endpoint is reachable from the public internet.
</Warning>

## Step 2: Configure PostgreSQL Replication

Use the default `aptible` database user to configure logical replication.

Create a local tunnel to your Database:

```bash theme={null}
aptible db:tunnel YOUR_DATABASE_HANDLE
```

Copy the connection URL from the tunnel output and connect with `psql` or another PostgreSQL client. Then run:

```sql theme={null}
CREATE PUBLICATION datastream_publication FOR ALL TABLES;

SELECT pg_create_logical_replication_slot('datastream_slot', 'pgoutput');

ALTER SYSTEM SET wal_sender_timeout = 0;

SELECT * FROM pg_replication_slots;
```

<Info>
  `wal_sender_timeout = 0` prevents idle replication connections from timing out when Datastream keeps the WAL stream open through the Aptible load balancer.
</Info>

## Step 3: Retrieve the Aptible CA Certificate

Download the Environment CA certificate so Google Datastream can verify the Database Endpoint certificate:

```bash theme={null}
aptible environment:ca_cert YOUR_ENVIRONMENT_HANDLE > aptible_ca.pem
```

You will upload `aptible_ca.pem` when creating the PostgreSQL source connection profile in Datastream.

## Step 4: Create Datastream Connection Profiles

### PostgreSQL Source

Create a PostgreSQL source connection profile in Google Datastream with these values:

* **Hostname**: the Aptible Database Endpoint hostname, such as `elb-xxx.aptible.in`
* **Port**: the Aptible Database Endpoint port
* **Username**: `aptible`
* **Password**: the Database credential password
* **Database name**: `db`, unless your Database uses a different name
* **Encryption**: Require SSL/TLS
* **Server verification**: enabled
* **CA certificate**: upload `aptible_ca.pem`
* **Connectivity**: IP allowlisting

Run the connection test before creating the profile.

### BigQuery Destination

Create a BigQuery destination connection profile in Datastream and select the Google Cloud project where replicated data should be written.

## Step 5: Create and Start the Stream

In Google Datastream, create a stream with the PostgreSQL source profile and BigQuery destination profile.

Use these source configuration values:

* **Replication slot name**: `datastream_slot`
* **Publication name**: `datastream_publication`

Choose the destination configuration and staleness limit that match your analytics requirements, then start the stream.

## Step 6: Validate Replication

After Datastream initializes and performs the initial backfill, open BigQuery and confirm the dataset and tables are present. You can run a query like:

```sql theme={null}
SELECT * FROM `your-project.your_dataset.your_table` LIMIT 100;
```

If the stream fails to connect, verify the Database Endpoint host and port, IP allowlist, TLS settings, and uploaded Aptible CA certificate.


# Test a PostgreSQL Database's schema on a new version
Source: https://www.aptible.com/docs/how-to-guides/database-guides/test-schema-new-version

The goal of this guide is to test the schema of an existing Database against another Database version in order to see if it's compatible with the desired version. The primary reason to do this is to ensure a Database's schema is compatible with a higher version before upgrading.

## Preparation

#### Step 0: Install the necessary tools

Install the [Aptible CLI](/docs/reference/aptible-cli/cli-commands/overview) and [PostgreSQL Client Tools](https://www.postgresql.org/download/). This guide uses the `pg_dumpall` and `psql` client tools.

#### Step 1: Configuration

Collect information on the Database you'd like to test and store it in the following environment variables for use later in the guide:

* `SOURCE_HANDLE` - The handle (i.e. name) of the Database.

* `SOURCE_ENVIRONMENT` - The handle of the environment theDatabase belongs to.

Example:

```sql theme={null}
SOURCE_HANDLE='source-db'
SOURCE_ENVIRONMENT='test-environment'
```

Collect information on the target Database and store it in in the following environment variables:

* `TARGET_HANDLE` - The handle (i.e. name) for the Database.

* `TARGET_VERSION` - The target PostgreSQL version. Run `aptible db:versions` to see a full list of options.

* `TARGET_ENVIRONMENT` - The handle of the environment to create the Database in.

Example:

```sql theme={null}
TARGET_HANDLE='schema-test'
TARGET_VERSION='14'
TARGET_ENVIRONMENT='test-environment'
```

#### Step 2: Create the target Database

Create a new Database running the desired version. Assuming the environment variables above are set, this command can be copied and pasted as-is to create the Database.

```sql theme={null}
aptible db:create "$TARGET_HANDLE" --type postgresql --version "$TARGET_VERSION" --environment "$TARGET_ENVIRONMENT"
```

By default, [`aptible db:create`](/docs/reference/aptible-cli/cli-commands/cli-db-create) creates a Database with a 1 GB of memory and 10 GB of disk space. This should be sufficient for most schema tests but, if more memory or disk is required, the `--container-size` and `--disk-size` arguments can be used.

## Execution

#### Step 1: Dump the schema

Create a [Database Tunnel](/docs/core-concepts/managed-databases/connecting-databases/database-tunnels) to the source Database using the Aptible CLI.

```sql theme={null}
aptible db:tunnel "$SOURCE_HANDLE" --environment "$SOURCE_ENVIRONMENT"
```

The tunnel will block the current terminal until it's stopped. In another terminal, collect the tunnel's information, which is printed by [`aptible db:tunnel`](/docs/reference/aptible-cli/cli-commands/cli-db-tunnel), and store it in the following environment variables:

* `SOURCE_URL` - The full URL of the Database tunnel.

* `SOURCE_PASSWORD` - The Database's password.

Example:

```sql theme={null}
SOURCE_URL='postgresql://aptible:pa$word@localhost.aptible.in:5432/db'
SOURCE_PASSWORD='pa$word'
```

Dump the schema into a file. `schema.sql` in this case.

```sql theme={null}
PGPASSWORD="$SOURCE_PASSWORD" pg_dumpall -d "$SOURCE_URL" --schema-only --no-password \
  | grep -E -i -v 'ALTER ROLE aptible .*PASSWORD' > schema.sql
```

The output of `pg_dumpall` is piped into `grep` in order to remove any SQL commands that may change the default `aptible` user's password. If these commands were to run on the target Database, it would be updated to match the source Database. This would result in the target Database's password no longer matching what's displayed in the [Aptible Dashboard](https://app.aptible.com) or printed by commands like [`aptible db:url`](/docs/reference/aptible-cli/cli-commands/cli-db-url) or [`aptible db:tunnel`](/docs/reference/aptible-cli/cli-commands/cli-db-tunnel) which could cause problems down the road.

You now have a copy of your Database's schema in `schema.sql`! The Database Tunnel can be closed by following the instructions that `aptible db:tunnel` printed when the tunnel started.

#### Step 2: Restore the schema

Create a [Database Tunnel](/docs/core-concepts/managed-databases/connecting-databases/database-tunnels) to the target Database using the Aptible CLI.

```sql theme={null}
aptible db:tunnel "$TARGET_HANDLE" --environment "$TARGET_ENVIRONMENT"
```

Again, the tunnel will block the current terminal until it's stopped. In another terminal, store the tunnel's full URL, which is printed by [`aptible db:tunnel`](/docs/reference/aptible-cli/cli-commands/cli-db-tunnel), in the `TARGET_URL` environment variable.

Example:

```sql theme={null}
TARGET_URL='postgresql://aptible:p@ssword@localhost.aptible.in:5432/db'
```

Apply the schema to the target Database.

```sql theme={null}
psql $TARGET_URL -f schema.sql > /dev/null
```

The output of `psql` can be noisy depending on the complexity of the source Database's schema. In order to reduce the noise, the output is redirected to `/dev/null` so that only error messages are displayed.

The following errors may come up when restoring the schema:

```sql theme={null}
ERROR:  role "aptible" already exists
ERROR:  role "postgres" already exists
ERROR:  database "db" already exists
```

These errors are expected because Aptible creates these resources on all PostgreSQL Databases when they are created. The errors are a result of the schema dump attempting to re-create the existing resources. If these are the only errors, the upgrade was successful!

If there are additional errors, they will need to be addressed in order to be able to upgrade the source Database to the desired version. Consult the [PostgreSQL Documentation](https://www.postgresql.org/docs/) for details about the errors you encounter.

Once you've updated the source Database's schema you can test the changes by deprovisioning the target Database, see the [Cleanup](/docs/how-to-guides/database-guides/test-schema-new-version#cleanup) section, and starting from the [Create the target Database](/docs/how-to-guides/database-guides/test-schema-new-version#create-the-target-database) step.

## Cleanup

#### Step 1: Deprovision the target Database

```sql theme={null}
aptible db:deprovision "$TARGET_HANDLE" --environment "$TARGET_ENVIRONMENT"
```

#### Step 2: Delete Final Backups (Optional)

If the `$TARGET_ENVIRONMENT` is configured to [retain final Database Backups](/docs/core-concepts/managed-databases/managing-databases/database-backups#retention-and-disposal), which is enabled by default, you may want to delete the final backups for all target Databases you created for this test.

You can obtain a list of final backups by running:

```sql theme={null}
aptible backup:orphaned --environment "$TARGET_ENVIRONMENT"
```

Then, delete the backup(s) by ID using the [`aptible backup:purge`](/docs/reference/aptible-cli/cli-commands/cli-backup-purge) command.


# Use mysqldump to test for upgrade incompatibilities
Source: https://www.aptible.com/docs/how-to-guides/database-guides/test-upgrade-incompatibiltiies



The goal of this guide is to use `mysqldump` to test the table definitions of an existing Database against another Database version in order to see if it's compatible with the desired version. The primary reason to do this is to ensure a Database is compatible with a higher version before upgrading without waiting for lengthy data-loading operations.

## Preparation

#### Step 0: Install the necessary tools

Install the [Aptible CLI](/docs/reference/aptible-cli/cli-commands/overview) and [MySQL](https://dev.mysql.com/doc/refman/5.7/en/installing.html). This guide uses the `mysqldump` and `mysql` client tools.

#### Step 1: Configuration

Collect information on the Database you'd like to test and store it in the following environment variables for use later in the guide:

* `SOURCE_HANDLE` - The handle (i.e. name) of the Database.

* `SOURCE_ENVIRONMENT` - The handle of the environment the Database belongs to.

Example:

```sql theme={null}
SOURCE_HANDLE='source-db'
SOURCE_ENVIRONMENT='test-environment'
```

Collect information on the target Database and store it in the following environment variables:

* `TARGET_HANDLE` - The handle (i.e., name) for the Database.

* `TARGET_VERSION` - The target MySQL version. Run `aptible db:versions` to see a full list of options. This must be within one General Availability version of the source Database.

* `TARGET_ENVIRONMENT` - The handle of the Environment to create the Database in.

Example:

```sql theme={null}
TARGET_HANDLE='upgrade-test'
TARGET_VERSION='8.0'
TARGET_ENVIRONMENT='test-environment'
```

#### Step 2: Create the target Database

Create a new Database running the desired version. Assuming the environment variables above are set, this command can be copied and pasted as-is to create the Database.

```sql theme={null}
aptible db:create "$TARGET_HANDLE" \
  --type mysql \
  --version "$TARGET_VERSION" \
  --environment "$TARGET_ENVIRONMENT"
```

By default, [`aptible db:create`](/docs/reference/aptible-cli/cli-commands/cli-db-create) creates a Database with 1 GB of memory and 10 GB of disk space. This is typically sufficient for testing table definition compatibility, but if more memory or disk is required, the `--container-size` and `--disk-size` arguments can be used.

## Execution

#### Step 1: Dump the table definition

In a terminal, create a [Database Tunnel](/docs/core-concepts/managed-databases/connecting-databases/database-tunnels) to the source Database using the Aptible CLI.

```sql theme={null}
aptible db:tunnel "$SOURCE_HANDLE" --environment "$SOURCE_ENVIRONMENT" --port 5432
```

The tunnel will block the current terminal until it's stopped. In another terminal, collect the tunnel's [Database Credentials](/docs/core-concepts/managed-databases/connecting-databases/database-credentials), which are printed by [`aptible db:tunnel`](/docs/reference/aptible-cli/cli-commands/cli-db-tunnel). Then dump the database and database object definitions into a file. `defs.sql` in this case.

```sql theme={null}
MYSQL_PWD="$PASSWORD" mysqldump  --user root --host localhost.aptible.in --port 5432 --all-databases --no-data --routines --events  > defs.sql
```

The following error may come up when dumping the table definitions:

```sql theme={null}
Unknown table 'COLUMN_STATISTICS' in information_schema (1109)
```

This is due to a new flag that is enabled by default in `mysqldump 8`. You can disable this flag and resolve the error by adding `--column-statistics=0` to the above command.

You now have a copy of your Database's database object definitions in `defs.sql`! The Database Tunnel can be closed by following the instructions that `aptible db:tunnel` printed when the tunnel started.

#### Step 2: Restore the table definitions

Create a [Database Tunnel](/docs/core-concepts/managed-databases/connecting-databases/database-tunnels) to the target Database using the Aptible CLI.

```sql theme={null}
aptible db:tunnel "$TARGET_HANDLE" --environment "$TARGET_ENVIRONMENT" --port 5432
```

Again, the tunnel will block the current terminal until it's stopped. In another terminal, apply the table definitions to the target Database.

```sql theme={null}
MYSQL_PWD="$PASSWORD" mysql --user aptible --host localhost.aptible.in --port 5432 < defs.sql
```

If there are any errors, they will need to be addressed in order to be able to upgrade the source Database to the desired version. Consult the [MySQL Documentation](https://dev.mysql.com/doc/) for details about the errors you encounter.

Once you've updated the source Database's table definitions, you can test the changes by deprovisioning the target Database, see the [Cleanup](/docs/how-to-guides/database-guides/test-upgrade-incompatibiltiies#cleanup) section, and starting from the [Create the target Database](/docs/how-to-guides/database-guides/test-upgrade-incompatibiltiies#create-the-target-database) step.

## Cleanup

#### Step 1: Deprovision the target Database

```sql theme={null}
aptible db:deprovision "$TARGET_HANDLE" --environment "$TARGET_ENVIRONMENT"
```

#### Step 2: Delete Final Backups (Optional)

If the `$TARGET_ENVIRONMENT` is configured to [retain final Database Backups](/docs/core-concepts/managed-databases/managing-databases/database-backups#retention-and-disposal), which is enabled by default, you may want to delete the final backups for all target Databases you created for this test.

You can obtain a list of final backups by running the following:

```sql theme={null}
aptible backup:orphaned --environment "$TARGET_ENVIRONMENT"
```

Then, delete the backup(s) by ID using the [`aptible backup:purge`](/docs/reference/aptible-cli/cli-commands/cli-backup-purge) command.


# Upgrade MongoDB
Source: https://www.aptible.com/docs/how-to-guides/database-guides/upgrade-mongodb



The goal of this guide is to upgrade a MongoDB [Database](/docs/core-concepts/managed-databases/managing-databases/overview) to a newer release. The process is quick and easy to complete but only works from one release to the next, so in order to upgrade multiple releases, the process must be completed multiple times.

## Preparation

#### Step 0: Install the necessary tools

Install the [Aptible CLI](/docs/reference/aptible-cli/cli-commands/overview) and the [MongoDB shell](https://www.mongodb.com/docs/v4.4/administration/install-community/), `mongo` .

#### Step 1: Configuration

Collect information on the Database you'd like to upgrade and store it in the following environment variables for use later in the guide:

* `DB_HANDLE` - The handle (i.e. name) of the Database.

* `ENVIRONMENT` - The handle of the environment the Database belongs to.

* `VERSION` - The desired MongoDB version. Run `aptible db:versions` to see a full list of options.

Example:

```bash theme={null}
DB_HANDLE='my-redis'
ENVIRONMENT='test-environment'
VERSION='4.0'
```

#### Step 2: Contact Aptible Support

An Aptible team member must update the Database's metadata to the new version in order to upgrade the Database. When contacting [Aptible Support](/docs/how-to-guides/troubleshooting/aptible-support) please adhere to the following rules to ensure a smooth upgrade process:

* Ensure that you have [Administrator Access](/docs/core-concepts/security-compliance/access-permissions#write-permissions) to the Database's Environment. If you do not, please have someone with access contact support or CC an [Account Owner or Deploy Owner](/docs/core-concepts/security-compliance/access-permissions) for approval.

* Use the same email address that's associated with your Aptible user account to contact support.

* Include the configuration values above. You may run the following command to generate a request with the required information:

```bash theme={null}
echo "Please upgrade our MongoDB database, ${ENVIRONMENT} - ${DB_HANDLE}, to version ${VERSION}. Thank you."
```

## Execution

#### Step 1: Restart the Database

Once support has updated the Database, restarting it will apply the change. You may do so at your convenience with the [`aptible db:reload`](/docs/reference/aptible-cli/cli-commands/cli-db-reload) CLI command:

```bash theme={null}
aptible db:reload "$DB_HANDLE" --environment "$ENVIRONMENT"
```

When upgrading a replica set, restart secondary members first, then the primary member.

#### Step 2: Tunnel into the Database

In a separate terminal, create a [Database Tunnel](/docs/core-concepts/managed-databases/connecting-databases/database-tunnels) to the Database using the Aptible CLI.

```bash theme={null}
aptible db:tunnel "$DB_HANDLE" --environment "$ENVIRONMENT"
```

The tunnel will block the current terminal until it's stopped. Collect the tunnel's full URL, which is printed by [`aptible db:tunnel`](/docs/reference/aptible-cli/cli-commands/cli-db-tunnel), and store it in the `DB_URL` environment variable in the original terminal.

Example:

```bash theme={null}
DB_URL='postgresql://aptible:pa$word@localhost.aptible.in:5432/db'
```

#### Step 3: Enable Backward-Incompatible Features

Run the [`setFeatureCompatibilityVersion`](https://www.mongodb.com/docs/manual/reference/command/setFeatureCompatibilityVersion/) admin command on the Database:

```bash theme={null}
echo "db.adminCommand({ setFeatureCompatibilityVersion: '${VERSION}' })" |
  mongo --ssl --authenticationDatabase admin "$DB_URL"
```


# Upgrade PostgreSQL with logical replication
Source: https://www.aptible.com/docs/how-to-guides/database-guides/upgrade-postgresql



The goal of this guide is to [upgrade a PostgreSQL Database](/docs/core-concepts/managed-databases/managing-databases/database-upgrade-methods) to a newer version by means of [logical replication](/docs/core-concepts/managed-databases/managing-databases/database-upgrade-methods#logical-replication). Aptible uses [pglogical](https://github.com/2ndQuadrant/pglogical) to create logical replicas.

> 📘 The main benefit of using logical replication is that the replica can be created beforehand and will stay up-to-date with the source Database until it's time to cut over to the new Database. This allows for upgrades to be performed with minimal downtime.

## Preparation

#### **Step 0: Prerequisites**

Install [Aptible CLI](/docs/reference/aptible-cli/cli-commands/overview) and the [PostgreSQL Client Tools,](https://www.postgresql.org/download/) `psql`.

#### **Step 1: Test the schema**

If data is being transferred to a Database running a different PostgreSQL version than the original, first check that the schema can be restored on the desired version by following the [How to test a PostgreSQL Database's schema on a new version](/docs/how-to-guides/database-guides/test-schema-new-version) guide.

#### **Step 2: Test the upgrade**

Testing the schema should catch a number of issues, but it's also recommended to test the upgrade before performing it in production. The easiest way to do this is to restore the latest backup of the Database and perform the upgrade against the restored Database. The restored Database should have the same Container size as the production Database.

Example:

```sql theme={null}
aptible backup:restore 1234
--handle upgrade-test
--container- size 4096
```

#### **Step 3: Configuration**

Collect information on the Database you'd like to upgrade and store it in the following environment variables for use later in the guide:

* `SOURCE_HANDLE` - The handle (i.e. name) of the Database.

* `ENVIRONMENT` - The handle of the Environment the Database belongs to.

Example:

```sql theme={null}
SOURCE_HANDLE = 'source-db'
ENVIRONMENT = 'test-environment'
```

Collect information on the replica and store it in the following environment variables:

* `REPLICA_HANDLE` - The handle (i.e., name) for the Database.

* `REPLICA_VERSION` - The desired PostgreSQL version. Run `aptible db:versions` to see a full list of options.

* `REPLICA_CONTAINER_SIZE` (Optional) - The size of the replica's container in MB. Having more memory and CPU available speeds up the initialization process up to a certain point. See the [Database Scaling](/docs/core-concepts/scaling/database-scaling#ram-scaling) documentation for a full list of supported container sizes.

Example:

```sql theme={null}
REPLICA_HANDLE = 'upgrade-test'
REPLICA_VERSION = '14'
REPLICA_CONTAINER_SIZE = 4096
```

#### **Step 4: Tunnel into the source Database**

In a separate terminal, create a [Database Tunnel](/docs/core-concepts/managed-databases/connecting-databases/database-tunnels) to the source Database using the `aptible db:tunnel` command.

Example:

```sql theme={null}
aptible db:tunnel "$SOURCE_HANDLE" --environment "$ENVIRONMENT"
```

The tunnel will block the current terminal until it's stopped. Collect the tunnel's full URL, which is printed by [`aptible db:tunnel`](/docs/reference/aptible-cli/cli-commands/cli-db-tunnel), and store it in the `SOURCE_URL` environment variable in the original terminal.

Example:

```sql theme={null}
SOURCE_URL = 'postgresql://aptible:pa$word@localhost.aptible.in:5432/db'
```

#### **Step 5: Check for existing pglogical nodes**

Each PostgreSQL database on the server can only have a single `pglogical` node. If there's already an existing node, the replica will fail setup. The following script will check for existing pglogical nodes.

```sql theme={null}
psql "$SOURCE_URL" --tuples-only --no-align --command \
  'SELECT datname FROM pg_database WHERE datistemplate IS FALSE' |

while IFS= read -r db; do
  psql "$SOURCE_URL" -v ON_ERROR_STOP=1 << EOF &> /dev/null
    \connect "$db"
    SELECT pglogical.pglogical_node_info();
EOF

  if [ $? -eq 0 ]; then
    echo "pglogical node found on $db"
  fi
done
```

If the command does not report any nodes, no action is necessary. If it does, either replication will have to be set up manually instead of using `aptible db:replicate --logical`, or the node will have to be dropped.

Note that if logical replication was previously attempted, but failed, then the node could be left behind from the previous attempt. See the [Cleanup](/docs/how-to-guides/database-guides/upgrade-postgresql#cleanup) section and follow the instructions for cleaning up the source Database.

#### **Step 6: Check for tables without a primary key**

Logical replication requires that rows be uniquely identifiable in order to function properly. This is most easily accomplished by ensuring all tables have a primary key.

The following script will iterate over all PostgreSQL databases on the Database server and list tables that do not have a primary key:

```sql theme={null}
psql "$SOURCE_URL" --tuples-only --no-align --command \
'SELECT datname FROM pg_database WHERE datistemplate IS FALSE' |

while IFS= read -r db; do
  echo "Database: $db"
  psql "$SOURCE_URL" << EOF
\connect "$db";

    SELECT tab.table_schema, tab.table_name
    FROM information_schema.tables tab
    LEFT JOIN information_schema.table_constraints tco
              ON tab.table_schema = tco.table_schema
              AND tab.table_name = tco.table_name
              AND tco.constraint_type = 'PRIMARY KEY'
    WHERE tab.table_type = 'BASE TABLE'
          AND tab.table_schema NOT IN('pg_catalog', 'information_schema', 'pglogical')
          AND tco.constraint_name IS NULL
    ORDER BY table_schema, table_name;
EOF
done
```

If all of the databases return `(0 rows)` then no action is necessary.

Example output:

```sql theme={null}
Database: db
You are now connected to database "db" as user "aptible".
 table_schema | table_name
--------------+------------
(0 rows)

Database: postgres
You are now connected to database "postgres" as user "aptible".
 table_schema | table_name
--------------+------------
(0 rows)
```

If any tables come back without a primary key, one can be added to an existing column or a new column with [`ALTER TABLE`](https://www.postgresql.org/docs/current/sql-altertable.html).

#### **Step 7: Create the replica**

The upgraded replica can be created ahead of the actual upgrade as it will stay up-to-date with the source Database.

```sql theme={null}
aptible db:replicate "$SOURCE_HANDLE" "$REPLICA_HANDLE" \
  --logical \
  --version "$REPLICA_VERSION" \
  --environment "$ENVIRONMENT" \
  --container-size "${REPLICA_CONTAINER_SIZE:-4096}"
```

If the command raises errors, review the operation logs output by the command for an explanation as to why the error occurred. In order to attempt logical replication after the issue(s) have been addressed, the source Database will need to be cleaned up. See the [Cleanup](/docs/how-to-guides/database-guides/upgrade-postgresql#cleanup) section and follow the instructions for cleaning up the source Database. The broken replica also needs to be deprovisioned in order to free up its handle to be used by the new replica:

```sql theme={null}
aptible db:deprovision "$REPLICA_HANDLE" --environment "$ENVIRONMENT"
```

If the operation is successful, then the replica has been successfully set up. All that remains is for it to finish initializing (i.e. pulling all existing data), then it will be ready to be cut over to.

> 📘 `pglogical` will copy the source Database's structure at the time the subscription is created. However, subsequent changes to the Database structure, a.k.a. Data Definition Language (DDL) commands, are not included in logical replication. These commands need to be applied to the replica as well as the source Database to ensure that changes to the data are properly replicated.

> `pglogical` provides a convenient `replicate_ddl_command` function that, when run on the source Database, applies a DDL command to the source Database then queues the statement to be applied to the replica. For example, to add a column to a table:

```sql theme={null}
SELECT pglogical.replicate_ddl_command('ALTER TABLE public.foo ADD COLUMN bar TEXT;');
```

> ❗️ `pglogical` creates temporary replication slots that may show up inactive at times, theses temporary slots must not be deleted. Deleting these slots will disrupt `pglogical`

## Execution

#### **Step 1: Tunnel into the replica**

In a separate terminal, create a [Database Tunnel](/docs/core-concepts/managed-databases/connecting-databases/database-tunnels) to the replica using the Aptible CLI.

```sql theme={null}
aptible db:tunnel "$REPLICA_HANDLE" --environment "$ENVIRONMENT"
```

The tunnel will block the current terminal until it's stopped. Collect the tunnel's full URL, which is printed by [`aptible db:tunnel`](/docs/reference/aptible-cli/cli-commands/cli-db-tunnel), and store it in the `REPLICA_URL` environment variable in the original terminal.

Example:

```sql theme={null}
REPLICA_URL='postgresql://aptible:passw0rd@localhost.aptible.in:5432/db'
```

#### **Step 2: Wait for initialization to complete**

While replicas are usually created very quickly, it can take some time to pull all of the data from the source Database depending on its disk footprint. The replica can be queried to see what tables still need to be initialized.

```sql theme={null}
SELECT * FROM pglogical.local_sync_status WHERE NOT sync_status = 'r';
```

If any rows are returned, the replica is still initializing. This query can be used in a short script to test and wait for initialization to complete on all databases on the replica:

```sql theme={null}
psql "$REPLICA_URL" --tuples-only --no-align --command \
  'SELECT datname FROM pg_database WHERE datistemplate IS FALSE' |

while IFS= read -r db; do
  while psql "$REPLICA_URL" --tuples-only --quiet << EOF | grep -E '.+'; do
    \connect "$db"
    SELECT * FROM pglogical.local_sync_status WHERE NOT sync_status = 'r';
EOF
    sleep 3
  done
done
```

There is a [known issue](https://github.com/2ndQuadrant/pglogical/issues/337) with `pglogical` in which, during replica initialization, replication may pause until the next time the source Database is written to. For production Databases, this usually isn't an issue since it's being actively used, but for Databases that aren't used much, like Databases that may have been restored to test logical replication, this issue can arise.

The following script works similarly to the one above, but it also creates a table, writes to it, then drops the table in order to ensure that initialization continues even if the source Database is idle:

```sql theme={null}
psql "$REPLICA_URL" --tuples-only --no-align --command \
  'SELECT datname FROM pg_database WHERE datistemplate IS FALSE' |

while IFS= read -r db; do
  while psql "$REPLICA_URL" --tuples-only --quiet << EOF | grep -E '.+'; do
    \connect "$db"
    SELECT * FROM pglogical.local_sync_status WHERE NOT sync_status = 'r';
EOF
    psql "$SOURCE_URL" -v ON_ERROR_STOP=1 --quiet << EOF
      \connect "$db"
      CREATE TABLE _aptible_logical_sync (col INT);
      INSERT INTO _aptible_logical_sync VALUES (1);
      DROP TABLE _aptible_logical_sync;
EOF

    sleep 3
  done
done
```

Once the query returns zero rows from the replica or one of the scripts completes, the replica has finished initializing, which means it's ready to be cut over to.

#### **Optional: Speeding Up Initialization**

Each index on a table adds overhead to inserting rows, so the more indexes a table has, the longer it will take to be copied over. This can cause large Databases or those with many indexes to take much longer to initialize. If the initialization process appears to be going slowly, all of the indexes (except for primary keys) can be disabled:

```sql theme={null}
psql "$REPLICA_URL" --tuples-only --no-align --command \
  'SELECT datname FROM pg_database WHERE datistemplate IS FALSE' |

while IFS= read -r db; do
  echo "Database: $db"
  psql "$REPLICA_URL" << EOF
    \connect "$db"

    UPDATE pg_index SET indisready = FALSE WHERE indexrelid IN (
      SELECT idx.indexrelid FROM pg_index idx
      INNER JOIN pg_class cls ON idx.indexrelid = cls.oid
      INNER JOIN pg_namespace nsp ON cls.relnamespace = nsp.oid
      WHERE nsp.nspname !~ '^pg_'
      AND nsp.nspname NOT IN ('information_schema', 'pglogical')
      AND idx.indisprimary IS FALSE
    );
EOF
done

# Reload in order to restart the current COPY operation without indexes
aptible db:reload "$REPLICA_HANDLE" --environment "$ENVIRONMENT"
```

After the replica has been initialized, the indexes will need to be rebuilt. This can still take some time for large tables but is much faster than the indexes being evaluated each time a row is inserted:

```sql theme={null}
psql "$REPLICA_URL" --tuples-only --no-align --command \
  'SELECT datname FROM pg_database WHERE datistemplate IS FALSE' |

while IFS= read -r db; do
  echo "Database: $db"
  psql "$REPLICA_URL" --tuples-only --no-align --quiet << EOF |
    \connect "$db"

    SELECT CONCAT('"', nsp.nspname, '"."', cls.relname, '"') FROM pg_index idx
      INNER JOIN pg_class cls ON idx.indexrelid = cls.oid
      INNER JOIN pg_namespace nsp ON cls.relnamespace = nsp.oid
      WHERE nsp.nspname !~ '^pg_'
      AND nsp.nspname NOT IN ('information_schema', 'pglogical')
      AND idx.indisprimary IS FALSE
      AND idx.indisready IS FALSE;
EOF

  while IFS= read -r index; do
    echo "Reindexing: $index"
    psql "$REPLICA_URL" --quiet << EOF
      \connect "$db"

      REINDEX INDEX CONCURRENTLY $index;
EOF
  done
done
```

If any indexes have issues reindexing `CONCURRENTLY` this keyword can be removed, but note that when not indexing concurrently, the table the index belongs to will be locked, which will prevent writes while indexing.

#### **Step 3: Enable synchronous replication**

Enabling synchronous replication ensures that all data that is written to the source Database is also written to the replica:

```sql theme={null}
psql "$SOURCE_URL" << EOF
  ALTER SYSTEM SET synchronous_standby_names=aptible_subscription;
  SELECT pg_reload_conf();
EOF
```

> ❗️ Performance Alert: synchronous replication ensures that transactions are committed on both the primary and replica databases simultaneously, which can introduce noticable latency on commit times, especially on databases with higher relative volumes of changes. In this case, you may want to ensure that you wait to enable synchronous replication until you are close to performing the cutover in order to minimize the impact of slower commits on the primary database.

#### **Step 4: Scale Services down**

This step is optional. Scaling all [Services](/docs/core-concepts/apps/deploying-apps/services) that use the source Database to zero containers ensures that they can’t write to the Database during the cutover. This will result in some downtime in exchange for preventing replication conflicts that can result from Services writing to both the source and replica Databases at the same time.

It's usually easiest to prepare a script that scales all Services down and another that scales them back up to their current values once the upgrade has been completed. Current container counts can be found in the [Aptible Dashboard](https://app.aptible.com) or by running [`APTIBLE_OUTPUT_FORMAT=json aptible apps`](/docs/reference/aptible-cli/cli-commands/cli-apps).

Example scale command:

```
aptible apps:scale --app my-app cmd --container-count 0
```

#### **Step 5: Update all Apps to use the replica**

Assuming [Database's Credentials](/docs/core-concepts/managed-databases/connecting-databases/database-credentials) are provided to Apps via the [App's Configuration](/docs/core-concepts/apps/deploying-apps/configuration), this can be done relatively easily using the [`aptible config:set`](/docs/reference/aptible-cli/cli-commands/cli-config-set) command. This step is also usually easiest to complete by preparing a script that updates all relevant Apps.

Example config command:

```sql theme={null}
aptible config:set --app my-app DB_URL='postgresql://user:passw0rd@db-stack-1234.aptible.in:5432/db'
```

#### **Step 6: Sync sequences**

Ensure that the sequences on the replica are up-to-date with the source Database:

```sql theme={null}
psql "$SOURCE_URL" --tuples-only --no-align --command \
  'SELECT datname FROM pg_database WHERE datistemplate IS FALSE' |

while IFS= read -r db; do
  psql "$SOURCE_URL" << EOF
    \connect "$db"
    SELECT pglogical.synchronize_sequence( seqoid ) FROM pglogical.sequence_state;
EOF
done
```

#### **Step 7: Stop replication**

Now that all the Apps have been updated to use the new replica, there is no need to replicate changes from the source Database.

Drop the `pglogical` subscriptions, nodes, and extensions from the replica:

```sql theme={null}
psql "$REPLICA_URL" --tuples-only --no-align --command \
  'SELECT datname FROM pg_database WHERE datistemplate IS FALSE' |

while IFS= read -r db; do
  psql "$REPLICA_URL" << EOF
    \connect "$db"
    SELECT pglogical.drop_subscription('aptible_subscription');
    SELECT pglogical.drop_node('aptible_subscriber');
    DROP EXTENSION pglogical;
EOF
done
```

Clear `synchronous_standby_names` on the source Database:

```sql theme={null}
psql "$SOURCE_URL" << EOF
  ALTER SYSTEM RESET synchronous_standby_names;
  SELECT pg_reload_conf();
EOF
```

#### **Step 8: Scale Services up**

Scale any Services that were scaled down to zero Containers back to their original number of Containers. If a script was created to do this, now is the time to run it.

Example scale command:

```sql theme={null}
aptible apps:scale --app my-app cmd --container-count 2
```

Once all of the Services have come back up, the upgrade is complete!

## Cleanup

#### Step 1: Vacuum and Analyze

Vacuuming the target Database after upgrading reclaims space occupied by dead tuples and analyzing the tables collects information on the table's contents in order to improve query performance.

```sql theme={null}
psql "$REPLICA_URL" --tuples-only --no-align --command \
  'SELECT datname FROM pg_database WHERE datistemplate IS FALSE' |

while IFS= read -r db; do
  psql "$REPLICA_URL" << EOF
    \connect "$db"

    VACUUM ANALYZE;
EOF
done
```

#### Step 2: Source Database

> 🚧 Caution: If you're cleaning up from a failed replication attempt and you're not sure if `pglogical` was being used previously, check with other members of your organization before performing cleanup as this may break existing `pglogical` subscribers.

Drop the `pglogical` replication slots (if they exist), nodes, and extensions:

```sql theme={null}
psql "$SOURCE_URL" --tuples-only --no-align --command \
  'SELECT datname FROM pg_database WHERE datistemplate IS FALSE' |

while IFS= read -r db; do
  psql "$SOURCE_URL" << EOF
    \connect "$db"

    SELECT pg_drop_replication_slot((
      SELECT pglogical.pglogical_gen_slot_name(
        '$db',
        'aptible_publisher_$REPLICA_ID',
        'aptible_subscription'
      )
    ));

    \set ON_ERROR_STOP 1

    SELECT pglogical.drop_node('aptible_publisher_$REPLICA_ID');
    DROP EXTENSION pglogical;
EOF
done
```

Note that you'll need to substitute `REPLICA_ID` into the script for it to properly run! If you don't remember what it is, you can always also run:

```sql theme={null}
SELECT pglogical.pglogical_node_info();
```

from a `psql` client to discover what the pglogical publisher is named.

If the script above raises errors about replication slots being active, then replication was not stopped properly. Ensure that the instructions in the [Stop replication](/docs/how-to-guides/database-guides/upgrade-postgresql#stop-replication) section have been completed.

#### Step 3: Reset max\_worker\_processes

[`aptible db:replicate --logical`](/docs/reference/aptible-cli/cli-commands/cli-db-replicate) may have increased the `max_worker_processes` on the replica to ensure that it has enough to support replication. Now that replication has been terminated, the setting can be set back to the default by running the following command:

```sql theme={null}
psql "$REPLICA_URL" --command "ALTER SYSTEM RESET max_worker_processes;"
```

See [How Logical Replication Works](/docs/reference/aptible-cli/cli-commands/cli-db-replicate#how-logical-replication-works) in the command documentation for more details.

#### **Step 4: Unlink the Databases**

Aptible maintains a link between replicas and their source Database to ensure the source Database cannot be deleted before the replica. To deprovision the source Database after switching to the replica, users with the appropriate [roles and permissions](/docs/core-concepts/security-compliance/access-permissions#full-permission-type-matrix) can unlink the replica from the source database. Navigate to the replica's settings page to complete the unlinking process.

#### **Step 5: Deprovision**

Once the original Database is no longer necessary, it should be deprovisioned, or it will continue to incur costs. Note that this will delete all automated Backups. If you'd like to retain the Backups, contact [Aptible Support](/docs/how-to-guides/troubleshooting/aptible-support) to update them.

```sql theme={null}
aptible db:deprovision "$SOURCE_HANDLE" --environment "$SOURCE_ENVIRONMENT"
```


# Upgrade Redis
Source: https://www.aptible.com/docs/how-to-guides/database-guides/upgrade-redis



This guide covers how to upgrade a Redis [Database](/docs/core-concepts/managed-databases/managing-databases/overview) to a newer release.

<Tip>
  Starting with Redis 6, the Access Control List feature was introduced by Redis. In specific scenarios, this change also changes how a Redis Database can be upgraded. To help describe when each upgrade method applies, we'll use the term `pre-ACL` to describe Redis version 5 and below, and `post-ACL` to describe Redis version 6 and beyond.
</Tip>

<Accordion title="Pre-ACL to Pre-ACL and Post-ACL to Post-ACL Upgrades">
  <Note>
    **Prerequisite:** Install the [Aptible CLI](/docs/reference/aptible-cli/cli-commands/overview)
  </Note>

  <Steps>
    <Step title="Collection Configuration Information">
      Collect information on the Database you'd like to upgrade and store it in the following environment variables for use later in the guide:

      * `DB_HANDLE` - The handle (i.e. name) of the Database.
      * `ENVIRONMENT` - The handle of the environment the Database belongs to.
      * `VERSION` - The desired Redis version. Run `aptible db:versions` to see a full list of options.

      ```bash theme={null}
        DB_HANDLE='my-redis'
        ENVIRONMENT='test-environment'
        VERSION='5.0-aof'
      ```
    </Step>

    <Step title="Contact the Aptible Support Team">
      An Aptible team member must update the Database's metadata to the new version in order to upgrade the Database. When contacting [Aptible Support](/docs/how-to-guides/troubleshooting/aptible-support) please adhere to the following rules to ensure a smooth upgrade process:

      * Ensure that you have [Administrator Access](/docs/core-concepts/security-compliance/access-permissions#write-permissions) to the Database's Environment. If you do not, please have someone with access contact support or CC an [Account Owner or Deploy Owner](/docs/core-concepts/security-compliance/access-permissions) for approval.
      * Use the same email address that's associated with your Aptible user account to contact support.
      * Include the configuration values above. You may run the following command to generate a request with the required information:

      ```bash theme={null}
        echo "Please upgrade our Redis database, ${ENVIRONMENT} - ${DB_HANDLE}, to version ${VERSION}. Thank you."
      ```
    </Step>

    <Step title="Restart the Database">
      Once support has updated the Database version, you'll need to restart the database to apply the upgrade. You may do so at your convenience with the [`aptible db:reload`](/docs/reference/aptible-cli/cli-commands/cli-db-reload) CLI command:

      ```bash theme={null}
        aptible db:reload --environment $ENVIRONMENT $DB_HANDLE
      ```
    </Step>
  </Steps>
</Accordion>

<Accordion title="Pre-ACL to Post-ACL Upgrades">
  <Accordion title="Method 1: Use Replication to Orchestrate a Minimal-Downtime Upgrade">
    <Note>
      **Prerequisite:** Install the [Aptible CLI](/docs/reference/aptible-cli/cli-commands/overview) and [Redis CLI](https://redis.io/docs/install/install-redis/)
    </Note>

    <Steps>
      <Step title="Collect Configuration Information">
        **Step 1: Configuration**

        Collect information on the Database you'd like to upgrade and store it in the following environment variables in a terminal session for use later in the guide:

        * `OLD_HANDLE` - The handle (i.e. name) of the Database.
        * `ENVIRONMENT` - The handle of the Environment the Database belongs to.

        Example:

        ```bash theme={null}
          SOURCE_HANDLE = 'old-db'
          ENVIRONMENT = 'test-environment'
        ```

        Collect information for the new Database and store it in the following environment variables:

        * `NEW_HANDLE` - The handle (i.e., name) for the Database.
        * `NEW_VERSION` - The desired Redis version. Run `aptible db:versions` to see a full list of options. Note that there are different ["flavors" of Redis](/docs/core-concepts/managed-databases/supported-databases/redis) for each version. Double-check that the new version has the same flavor as the original database's version.
        * `NEW_CONTAINER_SIZE` (Optional) - The size of the new Database's container in MB. You likely want this value to be the same as the original database's container size. See the [Database Scaling](/docs/core-concepts/scaling/database-scaling#ram-scaling) documentation for a full list of supported container sizes.
        * `NEW_DISK_SIZE` (Optional) - The size of the new Database's disk in GB. You likely want this value to be the same as the original database's disk size.

        Example:

        ```bash theme={null}
          NEW_HANDLE = 'upgrade-test'
          NEW_VERSION = '7.0'
          NEW_CONTAINER_SIZE = 2048
          NEW_DISK_SIZE = 10
        ```
      </Step>

      <Step title="Provision the new Database">
        Create the new Database using `aptible db:create`.

        Example:

        ```bash theme={null}
          aptible db:create "$NEW_HANDLE" \
          --type "redis" \
          --version "$NEW_VERSION" \
          --container-size $NEW_CONTAINER_SIZE \
          --disk-size $NEW_DISK_SIZE \
          --environment "$ENVIRONMENT"
        ```
      </Step>

      <Step title="Tunnel into the new Database">
        In a separate terminal, create a [Database Tunnel](/docs/core-concepts/managed-databases/connecting-databases/database-tunnels) to the new Database using the `aptible db:tunnel` command.

        Example:

        ```bash theme={null}
          aptible db:tunnel "$NEW_HANDLE" --environment "$ENVIRONMENT"
        ```

        The tunnel will block the current terminal until it's stopped. Collect the tunnel's full URL, which is printed by [aptible db:tunnel](/docs/reference/aptible-cli/cli-commands/cli-db-tunnel), and store it in the `NEW_URL` environment variable in the original terminal.

        Example:

        ```bash theme={null}
          NEW_URL ='redis://aptible:pa$word@localhost.aptible.in:6379'
        ```
      </Step>

      <Step title="Retrieve the Old Database's Database Credentials">
        To initialize replication, you'll need the [Database Credentials](/docs/core-concepts/managed-databases/connecting-databases/database-credentials) of the old database. We'll refer to these values as follows:

        * `OLD_HOST`
        * `OLD_PORT`
        * `OLD_PASSWORD`
      </Step>

      <Step title="Connect to the New Database">
        Using the Redis CLI in the original terminal, connect to the new database:

        ```bash theme={null}
          redis-cli -u $NEW_URL
        ```
      </Step>

      <Step title="Initialize Replication">
        Using the variables from Step 4, run the following commands on the new database to initialize replication.

        ```bash theme={null}
          REPLICAOF $OLD_HOST $OLD_PORT
          CONFIG SET masterauth $OLD_PASSWORD
        ```
      </Step>

      <Step title="Cutover to the New Database">
        When you're ready to cutover, point your Apps to the new Database and run `REPLICAOF NO ONE` via the Redis CLI to stop replication. Finally, deprovision the old database using the command aptible db:deprovision.
      </Step>
    </Steps>
  </Accordion>

  <Accordion title="Method 2: Dump and Restore to a new Redis Database">
    <Tip>
      We recommend Method 1 above, but you can also dump and restore to upgrade if you'd like. This method introduces extra downtime, as you must take your database offline before conducting the dump to prevent new writes and data loss.
    </Tip>

    <Note>
      **Prerequisite:** Install the [Aptible CLI](/docs/reference/aptible-cli/cli-commands/overview), [Redis CLI](https://redis.io/docs/install/install-redis/), and [rdb tool](https://github.com/sripathikrishnan/redis-rdb-tools)
    </Note>

    <Steps>
      <Step title="Collection Configuration Information">
        Collect information on the Database you'd like to upgrade and store it in the following environment variables in a terminal session for use later in the guide:

        * `OLD_HANDLE` - The handle (i.e. name) of the Database.
        * `ENVIRONMENT` - The handle of the Environment the Database belongs to

        Example:

        ```bash theme={null}
          SOURCE_HANDLE = 'old-db'
          ENVIRONMENT = 'test-environment'
        ```

        Collect information for the new Database and store it in the following environment variables:

        * `NEW_HANDLE` - The handle (i.e., name) for the Database.
        * `NEW_VERSION` - The desired Redis version. Run `aptible db:versions` to see a full list of options. Note that there are different ["flavors" of Redis](/docs/core-concepts/managed-databases/supported-databases/redis) for each version. Double-check that the new version has the same flavor as the original database's version.
        * `NEW_CONTAINER_SIZE` (Optional) - The size of the new Database's container in MB. You likely want this value to be the same as the original database's container size. See the [Database Scaling](/docs/core-concepts/scaling/database-scaling#ram-scaling) documentation for a full list of supported container sizes.
        * `NEW_DISK_SIZE` (Optional) - The size of the new Database's disk in GB. You likely want this value to be the same as the original database's disk size.

        Example:

        ```bash theme={null}
          NEW_HANDLE = 'upgrade-test'
          NEW_VERSION = '7.0'
          NEW_CONTAINER_SIZE = 2048
          NEW_DISK_SIZE = 10
        ```
      </Step>

      <Step title="Provision the New Database">
        Create the new Database using `aptible db:create`.

        Example:

        ```bash theme={null}
          aptible db:create "$NEW_HANDLE" \
          --type "redis" \
          --version "$NEW_VERSION" \
          --container - size $NEW_CONTAINER_SIZE \
          --disk - size $NEW_DISK_SIZE \
          --environment "$ENVIRONMENT"
        ```
      </Step>

      <Step title="Tunnel into the Old Database">
        In a separate terminal, create a [Database Tunnel](/docs/core-concepts/managed-databases/connecting-databases/database-tunnels) to the old Database using the `aptible db:tunnel` command.

        Example:

        ```bash theme={null}
          aptible db:tunnel "$NEW_HANDLE" --environment "$ENVIRONMENT"
        ```

        The tunnel will block the current terminal until it's stopped. Collect the tunnel's full URL, which is printed by `aptible db:tunnel`, and store it in the `OLD_URL` environment variable in the original terminal.

        Example:

        ```bash theme={null}
          OLD_URL = 'redis://aptible:pa$word@localhost.aptible.in:6379'
        ```
      </Step>

      <Step title="Dump the Old Database">
        Dump the old database to a file locally using rdb and the Redis CLI.

        Example:

        ```bash theme={null}
          redis-cli -u $OLD_URL --rdb dump.rdb
        ```
      </Step>

      <Step title="Tunnel into the New Database">
        In a separate terminal, create a [Database Tunnel](/docs/core-concepts/managed-databases/connecting-databases/database-tunnels) to the new Database using the `aptible db:tunnel` command, and save the Connection URL as `NEW_URL`.
      </Step>

      <Step title="Restore the Redis Dump using rdb">
        Using the rdb tool, restore the dump to the new Database.

        ```
          rdb --command protocol dump.rdb | redis - cli - u $NEW_URL--pipe
        ```
      </Step>

      <Step title="Cutover to the New Database">
        Point your Apps and other resources to your new database and deprovision the old database using the command `aptible db:deprovision`.
      </Step>
    </Steps>
  </Accordion>
</Accordion>


# Browse Guides
Source: https://www.aptible.com/docs/how-to-guides/guides-overview

Explore guides for using the Aptible platform

# Getting Started

<CardGroup>
  <Card title="Deploy your code" icon="globe" href="https://www.aptible.com/docs/custom-code-quickstart">
    <Badge>Custom Code</Badge>
  </Card>

  <Card title="Ruby Template" href="https://www.aptible.com/docs/ruby-quickstart" icon={<svg width="30" height="30" viewBox="0 0 256 255" xmlns="http://www.w3.org/2000/svg"><path d="M197.467 167.764l-145.52 86.41 188.422-12.787L254.88 51.393l-57.414 116.37z" fill="#CC342D"/><path d="M240.677 241.257L224.482 129.48l-44.113 58.25 60.308 53.528z" fill="#A11401"/><path d="M240.896 241.257l-118.646-9.313-69.674 21.986 188.32-12.673z" fill="#A11401"/><path d="M52.744 253.955l29.64-97.1L17.16 170.8l35.583 83.154z" fill="#E05A4D"/><path d="M180.358 188.05L153.085 81.226l-78.047 73.16 105.32 33.666z" fill="#CC342D"/><path d="M248.693 82.73l-73.777-60.256-20.544 66.418 94.321-6.162z" fill="#E05A4D"/><path d="M214.191.99L170.8 24.97 143.424.669l70.767.322z" fill="#CC342D"/><path d="M2.496 129.48l14.794 41.963 64.283-14.422 73.39-68.207 20.712-65.787L143.063 0 87.618 20.75C70.149 37 36.252 69.146 35.03 69.75c-1.21.618-22.384 40.639-32.534 59.73z" fill="#fff"/><path d="M54.442 54.094c37.86-37.538 86.667-59.716 105.397-40.818 18.72 18.898-1.132 64.823-38.992 102.349-37.86 37.525-86.062 60.925-104.78 42.027-18.73-18.885.515-66.032 38.375-103.558z" fill="#CC342D"/><path d="M52.744 253.916l29.408-97.409 97.665 31.376c-35.312 33.113-74.587 61.106-127.073 66.033z" fill="#9B1209"/><path d="M155.092 88.622l25.073 99.313c29.498-31.016 55.972-64.36 68.938-105.603l-94.01 6.29z" fill="#AA1401"/><path d="M248.847 82.833c10.035-30.282 12.35-73.725-34.966-81.791l-38.825 21.445 73.791 60.346z" fill="#B31000"/><path d="M0 202.935c1.39 49.979 37.448 50.724 52.808 51.162l-35.48-82.86L0 202.935z" fill="#9E1209"/></svg>}>
    <Badge>Sample Code</Badge>
  </Card>

  <Card
    title="NodeJS Template"
    href="https://www.aptible.com/docs/node-js-quickstart"
    icon={
<svg xmlns="http://www.w3.org/2000/svg" width="30" height="30" viewBox="0 0 58 64" fill="none">
<path d="M26.3201 0.681001C27.9201 -0.224999 29.9601 -0.228999 31.5201 0.681001L55.4081 14.147C56.9021 14.987 57.9021 16.653 57.8881 18.375V45.375C57.8981 47.169 56.8001 48.871 55.2241 49.695L31.4641 63.099C30.6514 63.5481 29.7333 63.7714 28.8052 63.7457C27.877 63.7201 26.9727 63.4463 26.1861 62.953L19.0561 58.833C18.5701 58.543 18.0241 58.313 17.6801 57.843C17.9841 57.435 18.5241 57.383 18.9641 57.203C19.9561 56.887 20.8641 56.403 21.7761 55.891C22.0061 55.731 22.2881 55.791 22.5081 55.935L28.5881 59.451C29.0221 59.701 29.4621 59.371 29.8341 59.161L53.1641 45.995C53.4521 45.855 53.6121 45.551 53.5881 45.235V18.495C53.6201 18.135 53.4141 17.807 53.0881 17.661L29.3881 4.315C29.2515 4.22054 29.0894 4.16976 28.9234 4.16941C28.7573 4.16905 28.5951 4.21912 28.4581 4.313L4.79207 17.687C4.47207 17.833 4.25207 18.157 4.29207 18.517V45.257C4.26407 45.573 4.43207 45.871 4.72207 46.007L11.0461 49.577C12.2341 50.217 13.6921 50.577 15.0001 50.107C15.5725 49.8913 16.0652 49.5058 16.4123 49.0021C16.7594 48.4984 16.9443 47.9007 16.9421 47.289L16.9481 20.709C16.9201 20.315 17.2921 19.989 17.6741 20.029H20.7141C21.1141 20.019 21.4281 20.443 21.3741 20.839L21.3681 47.587C21.3701 49.963 20.3941 52.547 18.1961 53.713C15.4881 55.113 12.1401 54.819 9.46407 53.473L2.66407 49.713C1.06407 48.913 -0.00993076 47.185 6.9243e-05 45.393V18.393C0.0067219 17.5155 0.247969 16.6557 0.698803 15.9027C1.14964 15.1498 1.79365 14.5312 2.56407 14.111L26.3201 0.681001ZM33.2081 19.397C36.6621 19.197 40.3601 19.265 43.4681 20.967C45.8741 22.271 47.2081 25.007 47.2521 27.683C47.1841 28.043 46.8081 28.243 46.4641 28.217C45.4641 28.215 44.4601 28.231 43.4561 28.211C43.0301 28.227 42.7841 27.835 42.7301 27.459C42.4421 26.179 41.7441 24.913 40.5401 24.295C38.6921 23.369 36.5481 23.415 34.5321 23.435C33.0601 23.515 31.4781 23.641 30.2321 24.505C29.2721 25.161 28.9841 26.505 29.3261 27.549C29.6461 28.315 30.5321 28.561 31.2541 28.789C35.4181 29.877 39.8281 29.789 43.9141 31.203C45.6041 31.787 47.2581 32.923 47.8381 34.693C48.5941 37.065 48.2641 39.901 46.5781 41.805C45.2101 43.373 43.2181 44.205 41.2281 44.689C38.5821 45.279 35.8381 45.293 33.1521 45.029C30.6261 44.741 27.9981 44.077 26.0481 42.357C24.3801 40.909 23.5681 38.653 23.6481 36.477C23.6681 36.109 24.0341 35.853 24.3881 35.883H27.3881C27.7921 35.855 28.0881 36.203 28.1081 36.583C28.2941 37.783 28.7521 39.083 29.8161 39.783C31.8681 41.107 34.4421 41.015 36.7901 41.053C38.7361 40.967 40.9201 40.941 42.5101 39.653C43.3501 38.919 43.5961 37.693 43.3701 36.637C43.1241 35.745 42.1701 35.331 41.3701 35.037C37.2601 33.737 32.8001 34.209 28.7301 32.737C27.0781 32.153 25.4801 31.049 24.8461 29.351C23.9601 26.951 24.3661 23.977 26.2321 22.137C28.0321 20.307 30.6721 19.601 33.1721 19.349L33.2081 19.397Z" fill="#8CC84B"/></svg>
}
  >
    <Badge>Sample Code</Badge>
  </Card>

  <Card
    title="Django Template"
    href="https://www.aptible.com/docs/python-quickstart"
    icon={
<svg width="30" height="30" viewBox="0 0 256 326" xmlns="http://www.w3.org/2000/svg" preserveAspectRatio="xMinYMin meet"><g fill="#2BA977"><path d="M114.784 0h53.278v244.191c-27.29 5.162-47.38 7.193-69.117 7.193C33.873 251.316 0 222.245 0 166.412c0-53.795 35.93-88.708 91.608-88.708 8.64 0 15.222.68 23.176 2.717V0zm1.867 124.427c-6.24-2.038-11.382-2.717-17.965-2.717-26.947 0-42.512 16.437-42.512 45.243 0 28.046 14.88 43.532 42.17 43.532 5.896 0 10.696-.332 18.307-1.351v-84.707z"/><path d="M255.187 84.26v122.263c0 42.105-3.154 62.353-12.411 79.81-8.64 16.783-20.022 27.366-43.541 39.055l-49.438-23.297c23.519-10.93 34.901-20.588 42.17-35.327 7.61-15.072 10.01-32.529 10.01-78.445V84.261h53.21zM196.608 0h53.278v54.135h-53.278V0z"/></g></svg>
}
  >
    <Badge>Sample Code</Badge>
  </Card>

  <Card
    title="Laravel Template"
    href="https://www.aptible.com/docs/php-quickstart"
    icon={
<svg height="30" viewBox="0 -.11376601 49.74245785 51.31690859" width="30" xmlns="http://www.w3.org/2000/svg"><path d="m49.626 11.564a.809.809 0 0 1 .028.209v10.972a.8.8 0 0 1 -.402.694l-9.209 5.302v10.509c0 .286-.152.55-.4.694l-19.223 11.066c-.044.025-.092.041-.14.058-.018.006-.035.017-.054.022a.805.805 0 0 1 -.41 0c-.022-.006-.042-.018-.063-.026-.044-.016-.09-.03-.132-.054l-19.219-11.066a.801.801 0 0 1 -.402-.694v-32.916c0-.072.01-.142.028-.21.006-.023.02-.044.028-.067.015-.042.029-.085.051-.124.015-.026.037-.047.055-.071.023-.032.044-.065.071-.093.023-.023.053-.04.079-.06.029-.024.055-.05.088-.069h.001l9.61-5.533a.802.802 0 0 1 .8 0l9.61 5.533h.002c.032.02.059.045.088.068.026.02.055.038.078.06.028.029.048.062.072.094.017.024.04.045.054.071.023.04.036.082.052.124.008.023.022.044.028.068a.809.809 0 0 1 .028.209v20.559l8.008-4.611v-10.51c0-.07.01-.141.028-.208.007-.024.02-.045.028-.068.016-.042.03-.085.052-.124.015-.026.037-.047.054-.071.024-.032.044-.065.072-.093.023-.023.052-.04.078-.06.03-.024.056-.05.088-.069h.001l9.611-5.533a.801.801 0 0 1 .8 0l9.61 5.533c.034.02.06.045.09.068.025.02.054.038.077.06.028.029.048.062.072.094.018.024.04.045.054.071.023.039.036.082.052.124.009.023.022.044.028.068zm-1.574 10.718v-9.124l-3.363 1.936-4.646 2.675v9.124l8.01-4.611zm-9.61 16.505v-9.13l-4.57 2.61-13.05 7.448v9.216zm-36.84-31.068v31.068l17.618 10.143v-9.214l-9.204-5.209-.003-.002-.004-.002c-.031-.018-.057-.044-.086-.066-.025-.02-.054-.036-.076-.058l-.002-.003c-.026-.025-.044-.056-.066-.084-.02-.027-.044-.05-.06-.078l-.001-.003c-.018-.03-.029-.066-.042-.1-.013-.03-.03-.058-.038-.09v-.001c-.01-.038-.012-.078-.016-.117-.004-.03-.012-.06-.012-.09v-21.483l-4.645-2.676-3.363-1.934zm8.81-5.994-8.007 4.609 8.005 4.609 8.006-4.61-8.006-4.608zm4.164 28.764 4.645-2.674v-20.096l-3.363 1.936-4.646 2.675v20.096zm24.667-23.325-8.006 4.609 8.006 4.609 8.005-4.61zm-.801 10.605-4.646-2.675-3.363-1.936v9.124l4.645 2.674 3.364 1.937zm-18.422 20.561 11.743-6.704 5.87-3.35-8-4.606-9.211 5.303-8.395 4.833z" fill="#ff2d20"/></svg>
}
  >
    <Badge>Sample Code</Badge>
  </Card>

  <Card title="Python Template" href="https://www.aptible.com/docs/deploy-demo-app" icon={<svg width="30" height="30" viewBox="0 0 256 255" xmlns="http://www.w3.org/2000/svg"><path d="M126.916.072c-64.832 0-60.784 28.115-60.784 28.115l.072 29.128h61.868v8.745H41.631S.145 61.355.145 126.77c0 65.417 36.21 63.097 36.21 63.097h21.61v-30.356s-1.165-36.21 35.632-36.21h61.362s34.475.557 34.475-33.319V33.97S194.67.072 126.916.072zM92.802 19.66a11.12 11.12 0 0 1 11.13 11.13 11.12 11.12 0 0 1-11.13 11.13 11.12 11.12 0 0 1-11.13-11.13 11.12 11.12 0 0 1 11.13-11.13z" fill="#3776AB"/><path d="M128.757 254.126c64.832 0 60.784-28.115 60.784-28.115l-.072-29.127H127.6v-8.745h86.441s41.486 4.705 41.486-60.712c0-65.416-36.21-63.096-36.21-63.096h-21.61v30.355s1.165 36.21-35.632 36.21h-61.362s-34.475-.557-34.475 33.32v56.013s-5.235 33.897 62.518 33.897zm34.114-19.586a11.12 11.12 0 0 1-11.13-11.13 11.12 11.12 0 0 1 11.13-11.131 11.12 11.12 0 0 1 11.13 11.13 11.12 11.12 0 0 1-11.13 11.13z" fill="#FFD43B"/></svg>}>
    <Badge>Sample Code</Badge>
  </Card>
</CardGroup>

# App

<CardGroup>
  <Card title="How deploy via Docker Image" icon="book-open-reader" href="https://www.aptible.com/docs/direct-docker-image-deploy-example" />

  <Card title="How to deploy to Aptible with CI/CD" icon="book-open-reader" href="https://www.aptible.com/docs/continuous-integration-provider-deployment" />

  <Card title="How to explose a web app to the internet" icon="book-open-reader" href="https://www.aptible.com/docs/expose-web-app" />

  <Card title="See more" icon="angles-right" href="https://www.aptible.com/docs/deployment-guides" />
</CardGroup>

# Database

<CardGroup>
  <Card title="How to automate database migrations" icon="book-open-reader" href="https://www.aptible.com/docs/automating-database-migrations" />

  <Card title="How to upgrade PostgreSQL with Logical Replication" icon="book-open-reader" href="https://www.aptible.com/docs/logical-replication" />

  <Card title="How to dump and restore MySQL" icon="book-open-reader" href="https://www.aptible.com/docs/mysql-dump-and-restore" />

  <Card title="See more" icon="angles-right" href="https://www.aptible.com/docs/database-guides" />
</CardGroup>

# Observability

<CardGroup>
  <Card title="How to deploy and use Grafana" icon="book-open-reader" href="https://www.aptible.com/docs/deploying-grafana-on-deploy" />

  <Card title="How to set up Elasticsearch Log Rotation" icon="book-open-reader" href="https://www.aptible.com/docs/elasticsearch-log-rotation" />

  <Card title="How to set up Datadog APM" icon="book-open-reader" href="https://www.aptible.com/docs/datadog-apm" />

  <Card title="See more" icon="angles-right" href="https://www.aptible.com/docs/observability-guides" />
</CardGroup>

# Account and Platform

<CardGroup>
  <Card title="Best Practices Guide" icon="book-open-reader" href="https://www.aptible.com/docs/best-practices-guide" />

  <Card title="How to achieve HIPAA compliance" icon="book-open-reader" href="https://www.aptible.com/docs/achieve-hipaa" />

  <Card title="How to minimize downtime caused by AWS outages" icon="book-open-reader" href="https://www.aptible.com/docs/business-continuity" />

  <Card title="See more" icon="angles-right" href="https://www.aptible.com/docs/platform-guides" />
</CardGroup>

# Support & Troubleshooting

<CardGroup>
  <Card title="Support Hub" icon="life-ring" href="/how-to-guides/troubleshooting/aptible-support" />

  <Card title="Common Errors & Issues" icon="book-open-reader" href="/how-to-guides/troubleshooting/common-errors-issues/overview" />

  <Card title="Database Support Answers" icon="database" href="/core-concepts/managed-databases/managing-databases/overview" />

  <Card title="Contact Support" icon="comment" href="https://contact.aptible.com/" />
</CardGroup>


# How to access operation logs
Source: https://www.aptible.com/docs/how-to-guides/observability-guides/access-operation-logs

For all operations performed, Aptible collects operation logs. These logs are retained only for active resources and can be viewed in the following ways.

## Using the Dashboard

* Within the resource summary by:

  * Navigating to the respective resource

  * Selecting the **Activity** tab<img alt="" />

  * Selecting **Logs**

* Within the **Activity** dashboard by:

  * Navigating to the **Activity** page

  * Selecting the **Logs** button for the respective operation

    * Note: This page only shows operations performed in the last 7 days.

## Using the CLI

* By using the [aptible operation:logs](/docs/reference/aptible-cli/cli-commands/cli-operation-logs) command

  * Note: This command only shows operations performed in the last 90 days.

* For actively running operations, by using

  * [`aptible logs`](/docs/core-concepts/observability/logs/overview) to stream all logs for an app or database


# Collect Prometheus Metrics from Apps
Source: https://www.aptible.com/docs/how-to-guides/observability-guides/collect-prometheus-metrics-from-apps

Learn how to collect Prometheus metrics from containerized apps running on Aptible.

When an App exposes Prometheus metrics on Aptible, a traditional external Prometheus scraper usually cannot collect accurate per-container metrics. Aptible Containers are ephemeral and sit behind Endpoints, so an external scraper reaches the Endpoint instead of individual Containers. With multiple Containers, that can produce round-robin samples instead of a complete per-container view.

Use a push-based collection pattern instead: each Container sends its metrics to a collector App running on Aptible, and that collector forwards metrics to your monitoring backend.

## Recommended Architecture

```text theme={null}
App Container -> Telegraf Collector App -> Monitoring Backend
```

This pattern works well with tools such as Telegraf because the collector can receive Prometheus-formatted metrics and forward them to an output destination like Datadog, InfluxDB, or another metrics backend.

## Set Up Push-Based Collection

<Steps>
  <Step title="Deploy a metrics collector">
    Deploy a separate App in the same Environment to run Telegraf or another collector that can receive Prometheus-formatted metrics.
  </Step>

  <Step title="Configure the collector input">
    Configure Telegraf with the Prometheus listener input, such as `[[inputs.prometheus_listener]]`, so it can receive metrics pushed by your app Containers.
  </Step>

  <Step title="Configure the collector output">
    Configure the output plugin for your monitoring backend, such as `[[outputs.datadog]]` for Datadog.
  </Step>

  <Step title="Push metrics from each app Container">
    Update your application to send its local Prometheus metrics endpoint to the collector on a regular interval.
  </Step>
</Steps>

## Ruby Example

This example reads metrics from a local Prometheus endpoint and posts them to a Telegraf collector:

```ruby theme={null}
require "net/http"

Thread.new do
  loop do
    begin
      metrics = Net::HTTP.get(URI("http://0.0.0.0:9394/metrics"))
      Net::HTTP.post(
        URI("https://your-telegraf-app.aptible.in:9126/metrics"),
        metrics,
        { "Content-Type" => "text/plain" }
      )
    rescue => e
      puts "Metrics push failed: #{e.message}"
    end

    sleep 15
  end
end
```

For Ruby applications, the `prometheus_exporter` gem can help collect and format metrics before you push them to your collector.

<Tip>
  Keep your push interval aligned with the retention and alerting needs of your monitoring backend. Shorter intervals improve visibility but increase network traffic and backend ingest volume.
</Tip>


# How to deploy and use Grafana
Source: https://www.aptible.com/docs/how-to-guides/observability-guides/deploy-use-grafana

Learn how to deploy and use Aptible-hosted analytics and monitoring with Grafana

## Overview

[Grafana](https://grafana.com/) is an open-source platform for analytics and monitoring. It's an ideal choice to use in combination with an [InfluxDB metric drain.](/docs/core-concepts/observability/metrics/metrics-drains/influxdb-metric-drain) Grafan is useful in a number of ways:

* It makes it easy to build beautiful graphs and set up alerts.

* It works out of the box with InfluxDB.

* It works very well in a containerized environment like Aptible.

## Set up

### Deploying with Terraform

The **easiest and recommended way** to set up Grafana on Aptible is using the [Aptible Metrics Terraform Module](https://registry.terraform.io/modules/aptible/metrics/aptible/latest). This provisions Aptible metric drains with pre-built Grafana dashboards and alerts for monitoring RAM and CPU usage for your Aptible apps and databases. This simplifies the setup of metric drains so you can start monitoring your Aptible resources immediately, all hosted within your Aptible account. If you would rather set it up from scratch, use this guide.

### Deploying via the CLI

#### Step 1: Provision a PostgreSQL database

Grafana needs a Database to store sessions and Dashboard definitions. It works great with [PostgreSQL](/docs/core-concepts/managed-databases/supported-databases/postgresql), which you can deploy on Aptible.

#### Step 2: Configure the database

Once you have created the PostgreSQL Database, create a tunnel using the [`aptible db:tunnel`](/docs/reference/aptible-cli/cli-commands/cli-db-tunnel) command, then connect using `psql` and run the following commands to create a `sessions` database for use by Grafana:

```sql theme={null}
CREATE DATABASE sessions;
```

Then, connect to the newly-created `sessions` database:

```sql theme={null}
\c sessions;
```

And finally, create a table for Grafana to store sessions in:

```sql theme={null}
CREATE TABLE session (
        key       CHAR(16) NOT NULL,
        data      BYTEA,
        expiry    INTEGER NOT NULL,
        PRIMARY KEY (key)
);
```

#### Step 3: Deploy the Grafana app

Grafana is available as a Docker image and can be configured using environment variables. As a result, you can use [deploying via Docker image](/docs/how-to-guides/app-guides/migrate-dockerfile-to-direct-image-deploy) to easily deploy Grafana on Aptible.

Here is the minimal deployment configuration to get you started. In the example below, you'll have to substitute a number of variables:

* `$ADMIN_PASSWORD`: Generate a strong password for your Grafana `admin` user.

* `$SECRET_KEY`: Generate a random string (40 characters will do).

* `$YOUR_DOMAIN`: The domain name you intend to use to connect to Grafana (e.g. `grafana.example.com`).

* `$DB_USERNAME`: The username for your PostgreSQL database. For a PostgreSQL database on Aptible, this will be `aptible`.

* `$DB_PASSWORD`: The password for your PostgreSQL database.

* `$DB_HOST`: The host for your PostgreSQL database.

* `$DB_PORT`: The port for your PostgreSQL database.

```sql theme={null}
aptible apps:create grafana

aptible deploy --app grafana --docker-image grafana/grafana \
        "GF_SECURITY_ADMIN_PASSWORD=$ADMIN_PASSWORD" \
        "GF_SECURITY_SECRET_KEY=$SECRET_KEY" \
        "GF_DEFAULT_INSTANCE_NAME=aptible" \
        "GF_SERVER_ROOT_URL=https://$YOUR_DOMAIN" \
        "GF_SESSION_PROVIDER=postgres" \
        "GF_SESSION_PROVIDER_CONFIG=user=$DB_USERNAME password=$DB_PASSWORD host=$DB_HOST port=$DB_PORT dbname=sessions sslmode=require" \
        "GF_LOG_MODE=console" \
        "GF_DATABASE_TYPE=postgres" \
        "GF_DATABASE_HOST=$DB_HOST:$DB_PORT" \
        "GF_DATABASE_NAME=db" \
        "GF_DATABASE_USER=$DB_USERNAME" \
        "GF_DATABASE_PASSWORD=$DB_PASSWORD" \
        "GF_DATABASE_SSL_MODE=require"
```

> 📘 There are many more configuration options available in Grafana. Review [Grafana's configuration documentation](http://docs.grafana.org/installation/configuration/) for more information.

#### Step 4: Expose Grafana

Finally, follow the [How do I expose my web app on the Internet?](/docs/how-to-guides/app-guides/expose-web-app-to-internet) tutorial to expose your Grafana app over the internet. Make sure to use the same domain you configured Grafana with (`$YOUR_DOMAIN` in the example above)!

If you haven't already done so during endpoint creation, enable Force SSL to redirect all HTTP traffic to HTTPS:

```shell theme={null}
aptible endpoints:https:modify --app grafana "$ENDPOINT_HOSTNAME" --force-ssl
```

## Using Grafana

#### Step 1: Log in

Once you've exposed Grafana, you can navigate to `$YOUR_DOMAIN` to access Grafana. Connect using the username `admin` and the password you configured above (`ADMIN_PASSWORD`).

#### Step 2: Connect to an InfluxDB Database

Once logged in to Grafana, you can connect Grafana to an [InfluxDB](/docs/core-concepts/managed-databases/supported-databases/influxdb) database by creating a new data source. To do so, click the Grafana icon in the top left, then navigate to data sources and click "Add data source".

The following assumes you have provisioned an InfluxDB database. You'll need to interpolate the following values

* `$INFLUXDB_HOST`: The hostname for your InfluxDB database. This is of the form `db-$STACK-$ID.aptible.in`.

* `$INFLUXDB_PORT`: The port for your InfluxDB database.

* `$INFLUXDB_USERNAME`: The username for your InfluxDB database. Typically `aptible`.

* `$INFLUXDB_PASSWORD`: The password.

These parameters are represented by the connection URL for your InfluxDB database in the Aptible dashboard and CLI. For example, if your connection URL is `https://foo:bar@db-qux-123.aptible.in:456`, then the parameters are:

* `$INFLUXDB_HOST`: `db-qux-123.aptible.in`

* `$INFLUXDB_PORT`: `456`

* `$INFLUXDB_USERNAME`: `foo`

* `$INFLUXDB_PASSWORD`: `bar`

Once you have those parameters in Grafana, use the following configuration for your data source:

* **Name**: Any name of your choosing. This will be used to reference this data source in the Grafana web interface.

* **Type**: InfluxDB

* **HTTP settings**:

  * **URL**: `https://$INFLUXDB_HOST:$INFLUXDB_PORT`.

  * **Access**: `proxy`

* **HTTP Auth**: Leave everything unchecked

* **Skip TLS Verification**: Do not select

* **InfluxDB Details**: - Database: If you provisioned this InfluxDB database on Aptible and/or are using it for an [InfluxDB database](/docs/core-concepts/managed-databases/supported-databases/influxdb) metric drain, set this to `db`. Otherwise, use the database of your choice. - User: `$INFLUXDB_USERNAME` - Password: `$INFLUXDB_PASSWORD`

Finally, save your changes.

#### Step 3: Set up Queries

Here are a few suggested queries to get started with an InfluxDB metric drain. These queries are designed with Grafana in mind. To copy those queries into Grafana, use the [raw text editor mode](http://docs.grafana.org/features/datasources/influxdb/#text-editor-mode-raw) in Grafana.

> 📘 In the queries below, `$__interval` and `$timeFilter` will automatically be interpolated by Grafana. Leave those parameters as-is.

**RSS Memory Utilization across all resources**

```sql theme={null}
SELECT MAX("memory_rss_mb") AS rss_mb
FROM "metrics"
WHERE $timeFilter
GROUP BY
        time($__interval),
        "app", "database", "service", "host"
        fill(null)
```

**CPU Utilization for a single App**

In the example below, replace `ENVIRONMENT` with the handle for your [environment](/docs/core-concepts/architecture/environments) and `HANDLE` with the handle for your [app](/docs/core-concepts/apps/overview)

```sql theme={null}
SELECT MEAN("milli_cpu_usage") / 1000 AS cpu
FROM "metrics"
WHERE
        environment = 'ENVIRONMENT' AND
        app = 'HANDLE' AND
        $timeFilter
GROUP BY
        time($__interval),
        "service", "host"
        fill(null)
```

#### Disk Utilization across all Databases

```sql theme={null}
SELECT LAST(disk_usage_mb) / LAST(disk_limit_mb) AS utilization
FROM "metrics"
WHERE
        "database" <> '' AND
        $timeFilter
GROUP BY
        time($__interval),
        "database", "service", "host"
        fill(null)
```

## Grafana documentation

Once you've added your first data source, you might also want to consider following [Grafana's getting started documentation](http://docs.grafana.org/guides/getting_started/) to familiarize yourself with Grafana.

> 📘 If you get an error connecting, use the [`aptible logs`](/docs/reference/aptible-cli/cli-commands/cli-logs) commands to troubleshoot.

> That said, an error logging in is very likely due to not properly creating the `sessions` database and the `session` table in it as indicated in [Configuring the database](/docs/how-to-guides/observability-guides/deploy-use-grafana#configuring-the-database).

## Upgrading Grafana

To upgrade Grafana, deploy the desired version to your existing app containers:

```sql theme={null}
aptible deploy --app grafana --docker-image grafana/grafana:VERSION
```

> 📘 **Doing a big upgrade?** If you need to downgrade, you can redeploy with a lower version. Alternatively, you can deploy a test Grafana app to ensure it works beforehand and deprovisioned the test app once complete.


# How to set up Elasticsearch Log Rotation
Source: https://www.aptible.com/docs/how-to-guides/observability-guides/elasticsearch-log-rotation



## Components

We recommend using a combination of Elasticsearch's native features to ensure you do not accumulate too many open indexes by backing up your indexes to S3 in your own AWS account:

* [Index Lifecycle Management](https://www.elastic.co/guide/en/elasticsearch/reference/current/index-lifecycle-management.html) can be configured to delete indexes over a certain age.
* [Snapshot Lifecycle Management](https://www.elastic.co/guide/en/elasticsearch/reference/current/snapshot-lifecycle-management.html) can be configured to back up indexes on a schedule, for example, to S3 using the Elasticsearch [S3 Repository Plugin](https://www.elastic.co/guide/en/elasticsearch/plugins/current/repository-s3.html), which is available by default.

## Configuring a snapshot repository in S3

**Step 1:** Create an S3 bucket. We will use "aptible\_logs" as the bucket name for this example.

**Step 2:** Create a dedicated user to minimize the permissions of the access key, which will be stored in the database. Elasticsearch recommends creating an IAM policy with the minimum access level required. They provide a [recommended policy here](https://www.elastic.co/guide/en/elasticsearch/plugins/current/repository-s3-repository.html#repository-s3-permissions).

**Step 3:** Register the snapshot repository using the [Elasticsearch API](https://www.elastic.co/guide/en/elasticsearch/reference/7.x/put-snapshot-repo-api.html) directly because the Kibana UI does not provide you a way to specify your IAM keypair. In this example, we'll call the repository "s3\_repository" and configure it to use the "aptible\_logs" bucket created above:

```bash theme={null}
curl -X PUT "https://username:password@localhost:9200/_snapshot/s3_repository?pretty" -H 'Content-Type: application/json' -d'
{
  "type": "s3",
  "settings": {
    "bucket" : "aptible_logs",
    "access_key": "AWS_ACCESS_KEY_ID",
    "secret_key": "AWS_SECRET_ACCESS_KEY",
    "protocol": "https",
    "server_side_encryption": true
  }
}
'
```

Be sure to provide the correct username, password, host, and port needed to connect to your database, likely as provided by the [database tunnel](/docs/core-concepts/managed-databases/connecting-databases/database-tunnels), if you're connecting that way.

[The full documentation of available options is here.](https://www.elastic.co/guide/en/elasticsearch/plugins/current/repository-s3-usage.html)

## Backing up your indexes

To backup your indexes, use Elasticsearch's [Snapshot Lifecycle Management](https://www.elastic.co/guide/en/elasticsearch/reference/current/snapshot-lifecycle-management.html) to automate daily backups of your indexes. In Kibana, you'll find these settings under Elasticsearch Management > Snapshot and Restore. Snapshots are incremental, so you can set the schedule as frequently as you like, but at least daily is recommended. You can find the [full documentation for creating a policy here](https://www.elastic.co/guide/en/kibana/7.x/snapshot-repositories.html#kib-snapshot-policy).

## Limiting the live retention

Now that you have a Snapshot Lifecycle policy configured to backup your data to S3, the final step is to ensure you delete indexes after a specific time in Elasticsearch. Deleting indexes will ensure both RAM and disk space requirements are relatively fixed, given a fixed volume of logs. For example, you may keep only 30 days in Elasticsearch, and if you need older indexes, you can retrieve them by restoring the snapshot from S3.

**Step 1:** Create a new policy by navigating to Elasticsearch Management > Index Lifecycle Policies. Under "Hot phase", disable rollover - we're already creating a new index daily, which should be sufficient. Enable the "Delete phase" and set it for 30 days from index creation (or to your desired live retention).

**Step 2:** Specify to Elasticsearch which new indexes you want this policy to apply automatically. In Kibana, go to Elasticsearch Management > Index Management, then click Index Templates. Create a new template using the Index pattern `logstash-*`. You can leave all other settings as default. This template will ensure all new daily indexes get the lifecycle policy applied.

```
{
  "index.lifecycle.name": "rotation"
}
```

**Step 3:** Apply the lifecycle policy to any existing indexes. Under Elasticsearch Management > Index Management, select one by one each `logstash-*` index, click Manage, and then Apply Lifecycle Policy. Choose the policy you created earlier. If you want to apply the policy in bulk, you'll need to use the [update settings API](https://www.elastic.co/guide/en/elasticsearch/reference/master/set-up-lifecycle-policy.html#apply-policy-multiple) directly.

## Snapshot Lifecycle Management as an alternative to Aptible backups

Aptible [database backups](/docs/core-concepts/managed-databases/managing-databases/database-backups) allow for the easy restoration of a backup to an Aptible database using a single [CLI command](/docs/reference/aptible-cli/cli-commands/cli-backup-restore). However, the data retained with [Snapshot Lifecycle Management](https://www.elastic.co/guide/en/elasticsearch/reference/current/snapshot-lifecycle-management.html) is sufficient to restore the Elasticsearch database in the event of corruption, and you can configure Elasticsearch take much more frequent backups.


# How to set up a self-hosted Elasticsearch Log Drain with Logstash and Kibana (ELK)
Source: https://www.aptible.com/docs/how-to-guides/observability-guides/elk

This guide will walk you through setting up a self-hosted Elasticsearch - Logstash - Kibana (ELK) stack on Aptible.

## Create an Elasticsearch database

Use the [`aptible db:create`](/docs/reference/aptible-cli/cli-commands/cli-db-create) command to create a new [Elasticsearch](/docs/core-concepts/managed-databases/supported-databases/elasticsearch) Database:

```
aptible db:create "$DB_HANDLE" --type elasticsearch
```

> 📘 Add the `--disk-size X` option to provision a larger-than-default Database.

## Set up a log drain

**Step 1:** In the Aptible dashboard, create a new [log drain](/docs/core-concepts/observability/logs/log-drains/overview):

<img alt="" />

**Step 2:** Select Elasticsearch as the destination

<img alt="" />

**Step 3:** Save the Log Drain:

<img alt="" />

## Set up Kibana

Kibana is an open-source, browser-based analytics and search dashboard for Elasticsearch. Follow our [Running Kibana](/docs/how-to-guides/observability-guides/setup-kibana) guide to deploying Kibana on Aptible.

## Set up Log Rotation

If you let logs accumulate in Elasticsearch, you'll need more and more RAM and disk space to store them. To avoid this, set up log archiving. We recommend archiving logs to S3. Follow the instructions in our [Elasticsearch Log Rotation](/docs/how-to-guides/observability-guides/elasticsearch-log-rotation) guide.


# How to export Activity Reports
Source: https://www.aptible.com/docs/how-to-guides/observability-guides/export-activity-reports

Learn how to export Activity Reports

## Overview

[Activity Reports](/docs/how-to-guides/observability-guides/export-activity-reports) provide historical data of all operations in a given environment, including operations executed on resources that were later deleted. These reports are generated on a weekly basis for each environment, and they can be accessed for the duration of the environment's existence.

## Using the Dashboard

Activity Reports can be downloaded in CSV format within the Aptible Dashboard by:

* Selecting the respective Environment

* Selecting the **Activity Reports** tab

<img alt="" />


# How to set up a self-hosted HTTPS Log Drain
Source: https://www.aptible.com/docs/how-to-guides/observability-guides/https-log-drain



[HTTPS log drains](/docs/core-concepts/observability/logs/log-drains/https-log-drains) enable you to direct logs to HTTPS endpoints. This feature is handy for configuring Logstash and redirecting logs to another location while applying filters or adding additional information. To that end, we provide a sample Logstash app you can deploy on Aptible to do so: [aptible/docker-logstash](https://github.com/aptible/docker-logstash).

Once you've deployed this app, expose it using the [How do I expose my web app on the Internet?](/docs/how-to-guides/app-guides/expose-web-app-to-internet)) guide and then create a new HTTPS log drain to route logs there.


# All Observability Guides
Source: https://www.aptible.com/docs/how-to-guides/observability-guides/overview

Explore guides for enhancing observability on Aptible

* [How to access operation logs](/docs/how-to-guides/observability-guides/access-operation-logs)

* [How to export Activity Reports](/docs/how-to-guides/observability-guides/export-activity-reports)

* [How to set up Datadog APM](/docs/how-to-guides/observability-guides/setup-datadog-apm)

* [How to set up application performance monitoring](/docs/how-to-guides/observability-guides/setup-application-performance-monitoring)

* [How to collect Prometheus metrics from containerized apps](/docs/how-to-guides/observability-guides/collect-prometheus-metrics-from-apps)

* [How to deploy and use Grafana](/docs/how-to-guides/observability-guides/deploy-use-grafana)

* [How to set up a self-hosted Elasticsearch Log Drain with Logstash and Kibana (ELK)](/docs/how-to-guides/observability-guides/elk)

* [How to set up Elasticsearch Log Rotation](/docs/how-to-guides/observability-guides/elasticsearch-log-rotation)

* [How to set up a Papertrail Log Drain](/docs/how-to-guides/observability-guides/papertrail-log-drain)

* [How to set up a self-hosted HTTPS Log Drain](/docs/how-to-guides/observability-guides/https-log-drain)

* [How to set up Kibana on Aptible](/docs/how-to-guides/observability-guides/setup-kibana)


# How to set up a Papertrail Log Drain
Source: https://www.aptible.com/docs/how-to-guides/observability-guides/papertrail-log-drain

Learn how to set up a PaperTrail Log Drain on Aptible

## Set up a Papertrail Logging Destination

**Step 1:** Sign up for a Papertrail account.

**Step 2:** In Papertrail, find the "Log Destinations" tab. Select "Create a Log Destination," then "Create":

<img alt="" />

<img alt="" />

<img alt="" />

**Step 3:** Once created, note the host and port Papertrail displays for your new log destination.

<img alt="" />

## Set up a Log Drain

**Step 1:** In the Aptible dashboard, create a new [log drain](/docs/core-concepts/observability/logs/log-drains/overview) by navigating to the "Log Drains" tab in the environment of your choice:

<img alt="" />

**Step 2:** Select Papertrail as the destination.

<img alt="" />

**Step 3:** Input the host and port you received earlier and save your changes.


# How to set up application performance monitoring
Source: https://www.aptible.com/docs/how-to-guides/observability-guides/setup-application-performance-monitoring

Learn how to set up application performance monitoring

## Overview

To fully utilize our APM solution with Aptible, we suggest integrating an APM tool directly within your app containers. This simple yet effective step will allow for seamless monitoring and optimization of your application's performance.

Most APM tools let you do so through a library that hooks into your app framework or server.

## New Relic

New Relic is a popular solution used by Aptible customers To monitor application's performance to optimize and improve its functionality. To set up New Relic with your Aptible resources, create a New Relic account and follow the [installation instructions for New Relic APM.](https://docs.newrelic.com/introduction-apm/)


# How to set up Datadog APM
Source: https://www.aptible.com/docs/how-to-guides/observability-guides/setup-datadog-apm

Guide for setting up Datadog Application Performance Monitoring (APM) on your Aptible apps

## Overview

Datadog APM (Application Performance Monitoring) can be configured with Aptible to monitor and analyze the performance of Aptible apps and databases in real-time.

<AccordionGroup>
  <Accordion title="Setting Up the Datadog Agent">
    To use the Datadog APM on Aptible, you'll need to deploy the Datadog Agent as an App on Aptible, set a few configuration variables, and expose it through a HTTPS endpoint.

    ```shell theme={null}
    aptible apps:create datadog-agent
    aptible config:set --app datadog-agent DD_API_KEY=foo DD_HOSTNAME=aptible
    aptible deploy --app datadog-agent --docker-image=datadog/agent:7
    aptible endpoints:https:create --app datadog-agent --default-domain cmd --internal
    ```

    The example above deploys the Datadog Agent v7 from Dockerhub, an endpoint with a default domain, and also sets two required configuration variables.

    * `DD_API_KEY` should be set to an [API Key](https://docs.datadoghq.com/account_management/api-app-keys/#api-keys) associated with your Datadog Organization.
    * `DD_HOSTNAME` is a hostname identifier. Because Aptible does not grant containers permission to runtime information, you'll need explicitly set a hostname. While this can be anything, we recommend using this variable to help identify what the agent is monitoring.

    <Note>
      If you intend to use the Datadog APM for Database Monitoring, you'll need to make some adjustments to point the Datadog Agent at the database(s) you want to monitor. We go over these changes in the Setting Up Database Monitoring section below.
    </Note>
  </Accordion>

  <Accordion title="Setting Up Applications">
    To deliver data to Datadog, you'll need to instrument your application for tracing, as well as connect it to the Datadog Agent.

    Datadog provides a number of guides on how to set up your application for tracing. Follow the guide most relevant for your application to set up tracing.

    * [All Tracing Guides](https://docs.datadoghq.com/tracing/guide/)
    * [All Tracing Libraries](https://docs.datadoghq.com/tracing/trace_collection/dd_libraries/)
    * [Tutorial - Enabling Tracing for a Java Application and Datadog Agent in Containers](https://docs.datadoghq.com/tracing/guide/tutorial-enable-java-containers/)
    * [Tutorial - Enabling Tracing for a Python Application and Datadog Agent in Containers](https://docs.datadoghq.com/tracing/guide/tutorial-enable-python-containers/)
    * [Tutorial - Enabling Tracing for a Go Application and Datadog Agent in Containers](https://docs.datadoghq.com/tracing/guide/tutorial-enable-go-containers/)

    To connect to the Datadog Agent, set the `DD_TRACE_AGENT_URL` configuration variable for each App.

    ```shell theme={null}
    aptible config:set --app yourapp DD_TRACE_AGENT_URL=https://app-42.on-aptible.com:443
    ```

    You'll want `DD_TRACE_AGENT_URL` to be set to the hostname of the endpoint you created, with `:443` appended to the end to specify the listening port 443.
  </Accordion>

  <Accordion title="Setting Up Databases for Metrics Collection">
    Datadog offers integrations for various databases, including integrations for Redis, PostgreSQL, and MySQL through the Datadog Agent.
    For each database you want to integrate with, you'll need to follow Datadog's specific integration guide to prepare the database.

    * [All Integrations](https://docs.datadoghq.com/integrations/)
    * [PostgreSQL Integration Guide](https://docs.datadoghq.com/integrations/postgres/?tab=host)
    * [Redis Integration Guide](https://docs.datadoghq.com/integrations/redisdb/?tab=host)
    * [MySQL Integration Guide](https://docs.datadoghq.com/integrations/mysql/?tab=host)

    In addition, you'll also need to adjust the Datadog Agent application deployed on Aptible to point at your databases. This involves creating a Dockerfile for the Datadog Agent and [Deploying with Git](https://www.aptible.com/docs/core-concepts/apps/deploying-apps/image/deploying-with-git/overview).
    How your Dockerfile looks will differ slightly depending on the database(s) you want to monitor but involves replacing the generic `$DATABASE_TYPE.d/conf.yaml` with one pointing at your database.

    For example, a Dockerfile pointing to a PostgreSQL database could look like this:

    ```Dockerfile theme={null}
    FROM datadog/agent:7
    COPY postgres.yaml /conf.d/postgres.d/conf.yaml
    ```

    Where `postgres.yaml` is a file in your repository with information that points at the PostgreSQL database.

    You can find specifics on how to configure each database type in Datadog's integration documentation under the `Host` tab.

    * [PostgreSQL Configuration](https://docs.datadoghq.com/integrations/postgres/?tab=host#host)
    * [Redis Configuration](https://docs.datadoghq.com/integrations/redisdb/?tab=host#configuration)
    * [MySQL Configuration](https://docs.datadoghq.com/integrations/mysql/?tab=host#configuration)

    <Note>
      If you followed the instructions earlier and deployed with a Docker Image, you'll need to complete a few extra steps to swap back to git-based deployments. You can find those [instructions here](/docs/how-to-guides/app-guides/deploying-docker-image-to-git)
    </Note>

    <Note>
      Depending on the type of Database you want to monitor, you may need to set additional configuration variables. Please refer to Datadog's documentation for specific instructions.
    </Note>
  </Accordion>
</AccordionGroup>


# How to set up Kibana on Aptible
Source: https://www.aptible.com/docs/how-to-guides/observability-guides/setup-kibana



> ❗️ These instructions apply only to Kibana/Elasticsearch versions 7.0 or higher. Earlier versions on Deploy did not make use of Elasaticsearch's native authentication or encryption, so we built our own Kibana App compatible with those versions, which you can find here: [aptible/docker-kibana](https://github.com/aptible/docker-kibana)

Deploying Kibana on Aptible is not materially different from deploying any other prepackaged software. Below we will outline the basic configuration and best practices for deploying [Elastic's official Kibana image](https://hub.docker.com/_/kibana).

## Deploying Kibana

Since Elastic provides prebuilt Docker images for Kibana, you can deploy their image directly using the [`aptible deploy`](/docs/reference/aptible-cli/cli-commands/cli-deploy) command:

```sql theme={null}
aptible deploy --app $HANDLE --docker-image kibana:7.8.1 \
  ELASTICSEARCH_HOSTS="$URL" \
  ELASTICSEARCH_USERNAME="$USERNAME" \
  ELASTICSEARCH_PASSWORD="$PASSWORD"
```

Kibana can take several minutes to start accepting requests. If you haven't already done so during endpoint creation, enable Force SSL and set the release health check timeout:

```shell theme={null}
aptible endpoints:https:modify --app $HANDLE "$ENDPOINT_HOSTNAME" \
        --force-ssl --release-healthcheck-timeout 300
```

For the above Elasticsearch settings, refer to the [database credentials](/docs/core-concepts/managed-databases/connecting-databases/database-credentials) of your Elasticsearch Database. You must input the `ELASTICSEARCH_HOSTS` variable in this format:`https://$HOSTNAME:$PORT/`.

> 📘 Specifying a Kibana image requires a specific version number tag. The `latest` tag is not supported. You must specify the same version for Kibana that your Elasticsearch database is running.

You can make additional customizations using environment variables; refer to Elastic's [Kibana environment variable documentation](https://www.elastic.co/guide/en/kibana/current/docker.html#environment-variable-config) for a list of available variables.

## Exposing Kibana

You will need to create an [HTTP(S) endpoint](/docs/core-concepts/apps/connecting-to-apps/app-endpoints/https-endpoints/overview) to expose Kibana for access. While Kibana requires authentication, and you should force users to connect via HTTPS, you should also consider using [IP Filtering](/docs/core-concepts/apps/connecting-to-apps/app-endpoints/ip-filtering) to prevent unwanted intrusion attempts.

## Logging in to Kibana

You can connect to Kibana using the username and password provided by your Elasticsearch database's [credentials](/docs/core-concepts/managed-databases/connecting-databases/database-credentials), or any other user credentials with appropriate permissions.

## Scaling Kibana

The [default memory limit](https://www.elastic.co/guide/en/kibana/current/production.html#memory) that Kibana ships with is 1.4 GB, so you should use a 2 GB container size at a minimum to avoid exceeding the memory limit. As an example, at the 1 GB default Container size, it takes 3 minutes before Kibana starts accepting HTTP requests - hence the release health check timeout should be set to 5 minutes as shown above.

You should not scale the Kibana App to more than one container. User session information is not shared between containers, and if you scale the service to more than one container, you will get stuck in an authentication loop.


# How to collect database-specific metrics using the New Relic agent
Source: https://www.aptible.com/docs/how-to-guides/observability-guides/setup-newrelic-agent-database

Learn how to collect database metrics using the New Relic agent on Aptible

## Overview

This guide provides instructions on how to use our sample repository to run the New Relic agent as an Aptible container and collect custom database metrics. The sample repository can be found at [Aptible's New Relic Metrics Example](https://github.com/aptible/newrelic-metrics-example/).

By following this guide, you will be able to deploy the New Relic agent alongside your database and collect database-specific metrics for monitoring and analysis.

## New Relic

The example repo demonstrates how to configure the New Relic Agent to monitor PostgreSQL databases hosted on Aptible and report custom metrics to your New Relic account. However, the Agent can also be configured to collect database-specific metrics for the following database types:

* [ElasticSearch](https://github.com/newrelic/nri-elasticsearch)
* [MongoDB](https://github.com/newrelic/nri-mongodb)
* [MySQL](https://github.com/newrelic/nri-mysql)
* [PostgreSQL](https://github.com/newrelic/nri-postgresql)
* [RabbitMQ](https://github.com/newrelic/nri-rabbitmq)
* [Redis](https://github.com/newrelic/nri-redisb)

The example repo already installs the packages for the above database types, so the configuration file would just need to be added for each specific database type needing to be monitored, based on using the example in the above New Relic repo links.

## Troubleshooting

* No metrics appearing in New Relic: Verify that your NEW\_RELIC\_LICENSE\_KEY is correct and that the agent is running. Use [aptible logs](/docs/reference/aptible-cli/cli-commands/cli-logs) or a [Log Drain]() to inspect logs from the agent to see if there are any specific errors blocking delivery of metrics.
* Connection issues: Ensure that the database connection URL is accessible from the Aptible container. In Aptible's platform, the agent must be running in the same Stack as the Aptible database(s) being monitored.


# Advanced Best Practices Guide
Source: https://www.aptible.com/docs/how-to-guides/platform-guides/advanced-best-practices-guide

Learn how to take your infrastructure to the next level with advanced best practices

# Overview

> 📘 Read our [Best Practices Guide](/docs/how-to-guides/platform-guides/best-practices-guide) before proceeding.

This guide will provide advanced information for users who want to maximize the value and usage of the Aptible platform. With these advanced best practices, you'll be able to deploy your infrastructure with best practices for performance, reliability, developer efficiency, and security.

## Planning

### Authentication

* Set up [SSO](/docs/core-concepts/security-compliance/authentication/sso).
  * Using an SSO provider can help enforce login policies, including password rotation, MFA requirements, and improve users' ability to audit and verify access is revoked upon workforce changes.

### Disaster Recovery

* Plan for Regional failure using our [Business Continuity guide](/docs/how-to-guides/platform-guides/minimize-downtown-outages)
  * While unprecedented, an AWS Regional failure will test the preparedness of any team. If the Recovery time objective and recovery point objective set by users are intended to cover a regional disaster, Aptible recommends creating a dedicated stack in a separate region as a baseline ahead of a potential regional failure.

### CI/CD Strategy

* Align the release process across staging and production
  * To minimize issues experienced in production, users should repeat the established working process for releasing a staging environment. This not only gives users confidence when deploying to production but should also allow users to reproduce any issues that arise in production within the staging environment. Follow [these steps](/docs/how-to-guides/app-guides/integrate-aptible-with-ci/overview) to integrate Aptible with a CI Platform.
* Use a build artifact for deployment.
  * Using [deploying via Docker image](/docs/how-to-guides/app-guides/migrate-dockerfile-to-direct-image-deploy) allows users to ensure the exact image that passed the testing process is deployed to production, and users may retain that exact image for any future needs. Docker provides users the ability to [tag images](https://docs.docker.com/engine/reference/commandline/tag/), which allows images to be uniquely identified and reused when needed.   Each git-based deployment introduces a chance that the resulting image may differ. If code passes internal testing and is deployed to staging one week and then production the next, the image build process may have a different result even if dependencies are pinned. The worst case scenario may be that users need to roll back to a prior version, but due to external circumstances that image can no longer be built. Image-based deploys also make it easier to [lint and scan images in CI](/docs/how-to-guides/platform-guides/image-vulnerability-scanning) before they reach production.

## Operational Practices

### Apps

* Ensure your migrations backwards compatible
  * For services with HTTP(S) Endpoint, Aptible employs a zero downtime strategy whereby for a brief period, both new and old containers are running simultaneously. While the migrations in `before_release` are run before the new containers are added to the load balancing pool, this does mean any migrations not compatible with the old running code may result in noticeable errors or downtime during deployment. It is important that migrations are backwards compatible to avoid these errors. More on the release process [here](/docs/core-concepts/apps/deploying-apps/releases/overview#services-with-endpoints).
* Configure processes to run as PID 1 to handle signals properly
  * Since Docker is essentially a process manager, it is important to properly configure Containers to handle signals. Docker (and by extension all Aptible platform features) will send signals to PID 1 in the container to instruct it to stop. If PID 1 is not in the process, or the process doesn't respond to SIGTERM well, users may notice undesirable effects when restarting, scaling, deploying your Apps, or when the container exceeds the memory limits. More on PID 1 [here](/docs/how-to-guides/app-guides/define-services#advanced-pid-1-in-your-container-is-a-shell).
* Use `exec` in the Procfile
  * When users specify a Procfile, but do not have an ENTRYPOINT, the [commands are interpreted by a shell](/docs/how-to-guides/app-guides/define-services#procfile-commands). Use `exec` to ensure the process assumes PID 1. More on PID 1 and `exec` [here](/docs/how-to-guides/app-guides/define-services#advanced-pid-1-in-your-container-is-a-shell).

### Services

* Use the APTIBLE\_CONTAINER\_SIZE variable where appropriate
  * Some types of processes, particularly Java applications, require setting the size of a memory heap.  Users can use the environment variable set by Aptible to ensure the process knows what the container size is.  This helps avoid over-allocating memory and ensures users can quickly scale the application without having to set the memory amount manually in your App. Learn more about this variable [here](/docs/core-concepts/scaling/memory-limits#how-do-i-know-the-memory-limit-for-a-container).
* Host static assets externally and use consistent naming conventions
  * There are two cases where the naming and or storage of static assets may cause issues:
    1. If each container generates static assets within itself when it starts, randomly assigned static assets will cause errors for services scaled to >1 container
    2. If assets are stored in the container image (as opposed to S3, for example), users may have issues during zero-downtime deployments where requests for static assets fail due to two incompatible code-bases running at the same time.
  * Learn more about serving static assets in [this tutorial](/docs/how-to-guides/app-guides/serve-static-assets)

### Databases

* Upgrade all Database volumes to GP3
  * Newly provisioned databases are automatically provisioned on GP3 volumes. The GP3 volume type provides a higher baseline of IO performance but, more importantly, allows ONLINE scaling of IOPs and throughput, so users can alleviate capacity issues without restarting the database. Users can upgrade existing databases with zero downtime using these [steps](https://www.aptible.com/changelog#content/changelog/easily-modify-databases-without-disruption-with-new-cli-command-aptible-db-modify.mdx). The volume type of existing databases can be confirmed at the top of each database page in the Aptible dashboard.

### Endpoints

* Use strict runtime health checks
  * By default, Aptible health checks only ensure a service is returning responses to HTTP requests, not that those requests are free of errors. By enabling strict health checks, Aptible will only route requests to containers if those containers return a 200 response to `/healthcheck`. Enabling strict health checks also allows users to configure the route Aptible checks to return healthy/unhealthy using the criteria established by the user. Enable strict runtime health checks using the steps [here](/docs/core-concepts/apps/connecting-to-apps/app-endpoints/https-endpoints/health-checks#strict-health-checks).

### Dependency Vulnerability Scanning

* Use Dockerfile linting and image vulnerability scanning in CI/CD before deploying to production, and keep scanning deployed images between releases.
  * Prefer [deploying via Docker image](/docs/how-to-guides/app-guides/migrate-dockerfile-to-direct-image-deploy) so you can scan the exact artifact that ships. Follow the full process in [Image and Vulnerability Scanning](/docs/how-to-guides/platform-guides/image-vulnerability-scanning).


# Best Practices Guide
Source: https://www.aptible.com/docs/how-to-guides/platform-guides/best-practices-guide

Learn how to deploy your infrastructure with best practices for setting up your Aptible account

## Overview

This guide will provide all the essential information you need to confidently make key setup decisions for your Aptible platform. With our best practices, you'll be able to deploy your infrastructure with best practices for performance, reliability, and security.

## Resource Planning

### Stacks

An [Aptible Stack](/docs/core-concepts/architecture/stacks) is the underlying virtualized infrastructure (EC2 instances, private network, etc.) on which resources (Apps, Databases) are deployed. Consider the following when planning and creating stacks:

* Establish Network Boundaries

  * Stacks provide network-level isolation of resources and are therefore used to protect production resources. Environments or apps used for staging, testing or other purposes that may be configured with less stringent security controls may have direct access to production resources if they are deployed in the same stack. There are also issues other than CPU/Memory limits, such as open file limits on the host, where it's possible for a misbehaving testing container to affect production resources. To prevent these scenarios, it is recommended to use stacks as network boundaries.

* Use IP Filtering with [Stack IP addresses](/docs/core-concepts/apps/connecting-to-apps/outbound-ips)

  * Partners or vendors that use IP filtering may require users to provide them with the outbound IP addresses of the apps they interact with. There are instances where Aptible may need to fail over to other IP addresses to maintain outbound internet connectivity on a stack. It is important to add all Stack IP Addresses to the IP filter lists.

### Environments

[Environments](/docs/core-concepts/architecture/environments) are used for access control, to control backup policy and to provide logical isolation.  Remember network isolation is established at the Stack level; Environments on the same Stack can talk to each other.  Environments are used to group resources by logging, retention, and access control needs as detailed below:

* Group resources based on least-access principle

  * Aptible uses Environments and Roles to [manage user access](/docs/core-concepts/security-compliance/access-permissions).  Frequently, teams or employees do not require access to all resources.  It is good practice to identify the least access required for users or groups, and restrict access to that minimum set of permissions.

* Group Databases based on backup retention needs

  * Backup needs for databases can vary greatly. For example, backups for Redis databases used entirely as an in-memory cache or transient queue, or replica databases used by BI tools are not critical, or even useful, for disaster recovery. These types of databases can be moved to other Environments with a shorter backup retention configured, or without cross-region copies. More on Database Retention and Disposal [here](/docs/core-concepts/managed-databases/managing-databases/database-backups#retention-and-disposal).

* Group resources based on logging needs

  * [Logs](/docs/core-concepts/observability/logs/overview) are delivered separately for each environment. When users have access and retention needs that are specific to different classes of resources (staging versus production), using separate environments is an excellent way to deliver logs to different destinations or to uniquely tag logs.

* Configure [Log Drains](/docs/core-concepts/observability/logs/log-drains/overview) for all environments

  * Reviewing the output of a process is a very important troubleshooting step when issues arise. Log Drains provide the output, and more: users can collect the request logs as recorded at the Endpoint, and may also capture Aptible SSH sessions to audit commands run in Ephemeral Containers.

* Configure [Metric Drains](/docs/core-concepts/observability/metrics/metrics-drains/overview) for all environments

* Monitoring resource usage is a key step to detect issues as early as possible. While it is imperative to set up metric drains in production environments, there is also value in setting up metric drains for staging environments.

## Operational Practices

### Services

[Services](/docs/core-concepts/apps/deploying-apps/services) are metadata that define how many Containers Aptible will start for an App, what Container Command they will run, their Memory Limits, and their CPU Limits. Here are some considerations to keep in mind when working with services:

* [Scale services](/docs/core-concepts/scaling/overview) horizontally where possible

* Aptible recommends horizontally scaling all services to multiple containers to ensure high-availability. This will allow the app's services to handle container failures gracefully by routing traffic to healthy containers while the failed container is restarted. Horizontal scaling also ensures continued effectiveness in the case that performance needs to be scaled up. Aptible also recommend following this practice for at least one non-production environment because this will allow users to identify any issues with horizontal scaling (reliance on local session storage for example) in staging, rather than in production.

* Avoid unnecessary tasks, commands and scripts in the ENTRYPOINT, CMD or [Procfile](/docs/how-to-guides/app-guides/define-services).

  * Aptible recommends users ensure containers do nothing but start the desired process such as the web server for example.  If the container downloads, installs or configures any software before running the desired process, this introduces both a chance for failure and a delay in starting the desired process.  These commands will run every time the container starts, including if the container restarts unexpectedly. Therefore, Aptible recommends ensuring the container starts serving requests immediately upon startup to limit the impact of such restarts.

### Endpoints

[Endpoints](/docs/core-concepts/apps/connecting-to-apps/app-endpoints/overview) let users expose Apps on Aptible to clients over the public internet or the Stack's internal network. Here are some considerations to keep in mind when setting up endpoints:

* TLS version

  * Use the `SSL_PROTOCOLS_OVERRIDE` [setting](/docs/core-concepts/apps/connecting-to-apps/app-endpoints/https-endpoints/https-protocols#ssl_protocols_override-control-ssl--tls-protocols) to set the desired acceptable TLS version. While TLS 1.0 and 1.1 can provide great backward compatibility, it is standard practice to allow only `TLSv1.2`, and even `TLSv1.2 PFS` to pass many security scans.

* SSL

  * Take advantage of the `FORCE_SSL` [setting](/docs/core-concepts/apps/connecting-to-apps/app-endpoints/https-endpoints/https-redirect#force_ssl-in-detail). Aptible can handle HTTP->HTTPS redirects on behalf of the app, ensuring all clients connect securely without having to enable or write such a feature into each service.

### Dependency Vulnerability Scanning

* Use Dockerfile linting and image vulnerability scanning in CI/CD before deploying to production, and keep scanning deployed images between releases.

  * Prefer [deploying via Docker image](/docs/how-to-guides/app-guides/migrate-dockerfile-to-direct-image-deploy) so you can scan the exact artifact that ships. Follow the full process in [Image and Vulnerability Scanning](/docs/how-to-guides/platform-guides/image-vulnerability-scanning).

### Databases

* Create and use [least-privilege-required users](/docs/core-concepts/managed-databases/connecting-databases/database-endpoints#least-privileged-access) on databases

  * While using the built-in `aptible` user may be convenient, for Databases which support it (MySQL, PostgreSQL, Mongo, ES 7), Aptible recommends creating a separate user that is granted only the permissions required by the application. This has two primary benefits:

    1. Limit the impact of security vulnerabilities because applications are not granted more permissions than they need

    2. If the need to remediate a credential leak arises, or if a user's security policy dictates that the user rotate credentials periodically, the only way to rotate database credentials without any downtime is to create separate database users and update apps to use the newly created user's credentials.  Rotating the `aptible` user credential requires notifying Aptible Support to update the API to avoid breaking functionality such as replication and Database Tunnels and any Apps using the credentials will lose access to the Database.

## Monitoring

* Set up monitoring for common errors:

  * The "container exceeded memory allocation" is logged when a container exceeds its RAM allocation. While the metrics in the Dashboard are captured every minute, if a Container exceeds its RAM allocation very quickly and is then restarted, the metrics in the Dashboard may not reflect the usage spike. Aptible recommends referring to logs as the authoritative source of information to know when a container exceeds [the memory allocation](/docs/core-concepts/scaling/memory-limits#memory-management).

  * [Endpoint errors](/docs/core-concepts/apps/connecting-to-apps/app-endpoints/https-endpoints/endpoint-logs#common-errors) occur when an app does not respond to a request. The existence and frequency of these errors are key indicators of issues affecting end users. Aptible recommends setting up alerts when runtime health check requests are failing as this will notify users when a portion of the containers are impacted, rather than waiting for all containers to fail before noticing an issue.

* Set up monitoring for database disk capacity and IOPS.

  * While disk capacity issues almost always cause obviously fatal issues, IOPS capacity exhaustion can also be incredibly impactful on application performance. Aptible recommends setting up alerts when users see sustained IOPS consumption near the limit for the disk. This will allow users to skip right from fielding "the application is slow" complaints right to identifying the root cause.

* Set up [application performance monitoring (APM)](/docs/how-to-guides/observability-guides/setup-application-performance-monitoring) for applications.

  * Tools like New Relic or Datadog's APM can give users with great insights into how well (or poorly) specific portions of an application are performing - both from an end user's perspective, and from a per-function perspective. Since they run in the codebase, these tools are often able to shed light for users on what specifically is wrong much more accurately than combing through logs or container metrics.

* Set up external availability monitoring.

  * The ultimate check of the availability of an application comes not from monitoring the individual pieces, but the system as a whole. Services like [Pingdom](https://www.pingdom.com/) can monitor uptime of an application, including discovering problems with services like DNS configuration, which fall outside of the scope of the Aptible platform.


# How to cancel my Aptible Account
Source: https://www.aptible.com/docs/how-to-guides/platform-guides/cancel-aptible-account

To cancel your Deploy account and avoid any future charges, please follow these steps in order.

<Warning>
  Customers are responsible for ensuring all resources are properly deprovisioned to avoid additional future charges. Please review all steps carefully.
</Warning>

1. Export any [database](/docs/core-concepts/managed-databases/overview) data that you need.
   * To export Aptible backups, [restore the backup](/docs/core-concepts/managed-databases/managing-databases/database-backups#restoring-from-a-backup) to a new database first.
   * Use the [`aptible db:tunnel CLI command`](/docs/reference/aptible-cli/cli-commands/cli-db-tunnel) and whichever tool your database supports to dump the database to your computer.
2. Delete [metric drains](/docs/core-concepts/observability/metrics/metrics-drains/overview)
   * [Metric drains](/docs/core-concepts/observability/metrics/metrics-drains/overview) for an [environment](/docs/core-concepts/architecture/environments) can be deleted by navigating to the environment's **Metric Drains** tab in the dashboard.
3. Delete [log drains](/docs/core-concepts/observability/logs/log-drains/overview)
   * Log drains for an [environment](/docs/core-concepts/architecture/environments) can be deleted by navigating to the environment's **Log Drains** tab in the dashboard.
4. Deprovision your [apps](/docs/core-concepts/apps/overview) from the dashboard or with the [`aptible apps:deprovision`](/docs/reference/aptible-cli/cli-commands/cli-apps-deprovision) CLI command.
   * Deprovisioning an [app](/docs/core-concepts/apps/overview) automatically deprovisions all of its [endpoints](/docs/core-concepts/apps/connecting-to-apps/app-endpoints/overview) as well.
5. Deprovision your [databases](/docs/core-concepts/managed-databases/overview) from the dashboard or with the [`aptible db:deprovision`](/docs/reference/aptible-cli/cli-commands/cli-db-deprovision) CLI command.
   * Monthly and daily backups are automatically deleted when the [database](/docs/core-concepts/managed-databases/overview) is deprovisioned.
6. Delete [database backups](/docs/core-concepts/managed-databases/managing-databases/database-backups)
   * Use the **delete all on page** option to delete the final backups for your [databases](/docs/core-concepts/managed-databases/overview).

     <Warning>
       Backups Warning: Please note Aptible will no longer have a copy of your data when you delete your backups. Please create your own backup if you need to retain a copy of the data.
     </Warning>
7. Deprovision the [environment](/docs/core-concepts/architecture/environments) from the dashboard.
   * You can deprovision environments once all the resources in that [environment](/docs/core-concepts/architecture/environments) have been deprovisioned. If you have not deleted all resources, you will see a message advising you to delete any remaining resources before you can successfully deprovision the [environment](/docs/core-concepts/architecture/environments).
8. Submit an account deletion request through the Dashboard to deprovision your [Dedicated Stack](/docs/core-concepts/architecture/stacks#dedicated-stacks) and, if applicable, remove Premium or Enterprise Support.
   * Only [Account Owners](/docs/core-concepts/security-compliance/access-permissions#account-owners) can submit an account deletion request.
   * Navigate to your organization's settings to access the account deletion form.
   * Confirm your organization name and provide a cancellation reason (both required).
   * The request automatically creates a support ticket with your account details and cancellation reason.
   * If this step is incomplete, you will incur charges until Aptible deprovisions the dedicated stack and removes paid support from your account. Aptible Support can only complete this step after you submit the account deletion form.

<Warning>
  Final Invoice: Please note you will likely receive one more invoice after deprovisioning for usage from the last invoice to the time of deprovisioning.
</Warning>

<Tip>
  Verifying you have successfully deprovisioned resources: You can review your estimated monthly costs and/or future invoices to verify that all resources have been successfully deprovisioned.
</Tip>


# How to create and deprovison dedicated stacks
Source: https://www.aptible.com/docs/how-to-guides/platform-guides/create-deprovision-dedicated-stacks

Learn how to create and deprovision dedicated stacks

## Overview

[Dedicated stacks](/docs/core-concepts/architecture/stacks#dedicated-stacks) automatically come with a [suite of security features](https://www.aptible.com/secured-by-aptible), high availability, regulatory practices (HIPAA BAAs), and advanced connectivity options, such as VPN and VPC Peering.

## Creating Dedicated Stacks

Dedicated can only be provisioned by [Aptible Support.](/docs/how-to-guides/troubleshooting/aptible-support) You can request a dedicated stack from the Aptible Dashboard by:

* Navigating to the **Stacks** page

* Selecting **New Dedicated Stack**<img alt="" />

* Filling out the Request Dedicated Stack form<img alt="" />

## Deprovisoning Stacks

<Info> A dedicated stack can only successfully be deprovisioned once all of the environments and their respective resources have been deprovisioned. See related guide: [How to deprovision each type of resource](/docs/how-to-guides/platform-guides/delete-environment)</Info>

[Stacks](/docs/core-concepts/architecture/stacks) can only be deprovisioned by contacting [Aptible Support.](/docs/how-to-guides/troubleshooting/aptible-support)


# How to create environments
Source: https://www.aptible.com/docs/how-to-guides/platform-guides/create-environment



Learn how to create an [environment](/docs/core-concepts/architecture/environments)

## Using the Dashboard

Within the Aptible Dashboard, you can create an environment one of two ways:

* Using the **Deploy** tool <img alt="" />

* From the **Environments** page by selecting **Create Environment**<img alt="" />


# How to delete environments
Source: https://www.aptible.com/docs/how-to-guides/platform-guides/delete-environment



Learn how to delete/deprovision [environments](/docs/core-concepts/architecture/environments)

## Using the Dashboard

> ⚠️ Ensure you understand the impact of deprovisioning each resource type and make any necessary preparations, such as exporting Database data, before proceeding

An environment can only be deprovisioned from the Dashboard by:

* Navigating to the given environment

* Selecting the **Settings** tab

* Selecting **Deprovision Environment**<img alt="" />

> 📘 An environment can only successfully be deprovisioned once all of the resources within that Environment have been deprovisioned. The following guide describes how to deprovision each type of resource.


# How to deprovision resources
Source: https://www.aptible.com/docs/how-to-guides/platform-guides/deprovision-resources



First, review the [resource-specific restoration options](/docs/how-to-guides/platform-guides/restore-resources) to understand the impact of deprovisioning each type of resource and make any necessary preparations, such as exporting Database data, before proceeding.

## Apps

Deprovisioning an App also deprovisions its [Endpoints](/docs/core-concepts/apps/connecting-to-apps/app-endpoints/overview). [Apps](/docs/core-concepts/apps/overview) can be deprovisioned using the [`aptible apps:deprovision`](/docs/reference/aptible-cli/cli-commands/cli-apps-deprovision) CLI command or through the Dashboard:

* Select the App

* Select the **Deprovision** tab

* Follow the prompt

## Database Backups

Automated [Backups](/docs/core-concepts/managed-databases/managing-databases/database-backups) are deleted per the Environment's [backup retention policy](/docs/core-concepts/managed-databases/managing-databases/database-backups#retention-and-disposal) when the Database is deprovisioned. Manual backups, created using the [`aptible db:backup`](/docs/reference/aptible-cli/cli-commands/cli-db-backup) CLI command, must be deleted using the [`aptible backup:purge`](/docs/reference/aptible-cli/cli-commands/cli-backup-purge) CLI command or through the Dashboard:

* Select the **Backup Management** tab within the desired Environment.

* Select "**Permanently remove this backup**" for backups marked as Manual.

## Databases

[Databases](/docs/core-concepts/managed-databases/managing-databases/overview) can be deprovisioned using the [`aptible db:deprovision`](/docs/reference/aptible-cli/cli-commands/cli-db-deprovision) CLI command or through the Dashboard:

* Select the desired Database.

* Select the **Deprovision** tab.

* Follow the prompt.

## Log and Metric Drains

Delete Log and Metric Drains in the Dashboard:

* Select the Log Drains or Metric Drains tabs within each Environment.

* Select **Delete** on the top right of each drain.

## Environments

[Environments](/docs/core-concepts/architecture/environments) can only be deprovisioned after all of the resources in the Environment have been deprovisioned. Environments can only be deprovisioned through the Dashboard:

* Select the **Deprovision** tab within the Environment.

* Follow the prompt.


# Heroku to Aptible Migration Guide
Source: https://www.aptible.com/docs/how-to-guides/platform-guides/heroku-migration

A comprehensive guide for migrating applications from Heroku to Aptible

## Overview

If you are searching for a Heroku alternative, particularly a Heroku Enterprise alternative, Aptible is one of the strongest platform-as-a-service options to evaluate. For teams that need a Heroku-like developer experience but stronger security, isolation, and compliance foundations, Aptible is a natural next step.

Aptible offers simple, abstracted deployment of apps, databases, and infrastructure while providing dedicated infrastructure isolation, enforced security controls, and built-in compliance support for frameworks such as HIPAA, HITRUST, and SOC 2. These capabilities are especially important for startups operating in regulated industries and enterprise teams with strict security, reliability, and audit requirements.

[**Refer to the Security & Compliance docs for more information on our approach to security and compliance, including the specific controls we satisfy.**](/docs/core-concepts/security-compliance/overview)

If you are evaluating alternatives due to[ recent changes to Heroku’s Enterprise offering](https://www.heroku.com/blog/an-update-on-heroku/), you're in the right place. Many teams are reassessing their infrastructure strategy and looking for a platform that preserves developer velocity while strengthening security, compliance posture, and operational control.

This guide will help you both evaluate Aptible and outline a clear path for a smooth migration, including:

* Heroku vs Aptible comparison
* Key terminology mapping
* Technical migration steps:
  * Private Spaces to Dedicated Stacks
  * Projects to Environments
  * Dynos to containers
  * Heroku Postgres and Redis to Aptible-managed databases
  * Auditing add-ons
  * Reconfiguring endpoints and networking
  * Minimizing downtime during cutover

<Info>
  **Migrating from Heroku Shield?** If you're currently running compliance-focused workloads on Heroku Shield and handling regulated data such as PHI, see the [Heroku Shield to Aptible Migration Guide](/docs/how-to-guides/platform-guides/heroku-shield-migration) for Shield-specific guidance.
</Info>

<Tip>
  If you require further assistance or guidance during your migration, please [contact Aptible Support](https://app.aptible.com/support). White-glove migration services are also available for teams that want hands-on assistance.
</Tip>

## FAQs

<AccordionGroup>
  <Accordion title="Why migrate from Heroku to Aptible?">
    Aptible is a security, compliance, and reliability-focused platform as a service (PaaS). Migrating to Aptible enables you to instantly adopt a stronger security and compliance posture, with built-in support for frameworks such as HIPAA, HITRUST, and SOC 2, while maintaining the ease of use and developer experience you may already be familiar with from Heroku.

    Teams typically migrate to Aptible when they need more robust security controls, stronger compliance guarantees, or higher reliability, without taking on the operational burden of managing their own infrastructure.
  </Accordion>

  <Accordion title="How does Aptible pricing compare to Heroku?">
    If you're coming from Heroku's standard platform, Aptible's pricing model will feel familiar: usage-based billing, simple line items, and no long-term lock-ins or steep minimums.

    If you're migrating from Heroku Enterprise or Shield specifically, Aptible differs in two important ways: Aptible does not require a 12-month contract, and Aptible does not enforce high minimum spend thresholds. This makes it easier to adopt without long-term financial commitments.

    [Learn more about pricing](/docs/reference/pricing).
  </Accordion>

  <Accordion title="Can I keep using a Procfile?">
    Yes. Heroku requires a Procfile to define application processes, but on Aptible, Procfiles are optional.

    If no Procfile is present, Aptible will infer the service command from the Dockerfile `CMD` instruction. This is referred to as an [Implicit Service](/docs/how-to-guides/app-guides/define-services#how-to-define-services).

    You can continue using a Procfile if your application has multiple services or process types. Procfile syntax is compatible between Heroku and Aptible.

    **Note:** If you are [deploying via Docker image](/docs/how-to-guides/app-guides/migrate-dockerfile-to-direct-image-deploy) (deploying a pre-built image from a container registry), you must place your Procfile at `/.aptible/Procfile` and your `.aptible.yml` at `/.aptible/.aptible.yml` inside your Docker image. See [`Procfiles and .aptible.yml when deploying via Docker image`](/docs/core-concepts/apps/deploying-apps/image/deploying-with-docker-image/procfile-aptible-yml-direct-docker-deploy) for details.
  </Accordion>
</AccordionGroup>

## Heroku vs Aptible comparison

The table below summarizes key differences across compliance, developer experience, and pricing.

| Category                          | Heroku                             | Aptible                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| --------------------------------- | ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Compliance**                    |                                    |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| HIPAA Eligibility                 | Available (Enterprise/Shield)      | Included                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| HITRUST Inheritance               | Not available                      | Included                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| BAA Support                       | Available (Enterprise/Shield)      | Included                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| Encryption in Transit and at Rest | Included                           | Included, by default                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| Managed Intrusion Detection       | Not available                      | Included, by default                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| 24/7 SRE Monitoring               | Available with additional fee      | Included, by default                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| Automated Backups                 | Included, plan-dependent retention | Included, by default                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| Granular Access Control           | Limited                            | Included, by default                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| Infrastructure Isolation          | Included (Private Spaces)          | Included ([Dedicated Stacks](/docs/core-concepts/architecture/stacks))                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| **Developer Experience**          |                                    |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| Runtime Model                     | Dynos                              | [Docker containers](/docs/core-concepts/architecture/containers/overview)                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| Build System                      | Buildpacks                         | Dockerfile-based                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| Traffic Routing                   | Heroku Router                      | Explicit [Endpoints](/docs/core-concepts/apps/connecting-to-apps/app-endpoints/overview)                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| Automatic Rollbacks               | Limited                            | Included, by default                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| Zero-downtime deploys             | Included, by default               | Included, by default                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| Public and Private Access         | Limited                            | Available (Public and Private [Endpoints](/docs/core-concepts/apps/connecting-to-apps/app-endpoints/overview) supported)                                                                                                                                                                                                                                                                                                                                                                                                                   |
| Managed Databases                 | Heroku Postgres & Redis            | [PostgreSQL](/docs/core-concepts/managed-databases/supported-databases/postgresql), [MySQL](/docs/core-concepts/managed-databases/supported-databases/mysql), [Redis](/docs/core-concepts/managed-databases/supported-databases/redis), [Elasticsearch](/docs/core-concepts/managed-databases/supported-databases/elasticsearch), [RabbitMQ](/docs/core-concepts/managed-databases/supported-databases/rabbitmq), [InfluxDB](/docs/core-concepts/managed-databases/supported-databases/influxdb), [SFTP](/docs/core-concepts/managed-databases/supported-databases/sftp) |
| **Pricing**                       |                                    |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| Compute Pricing Model             | Dyno tiers                         | Container-based pricing                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| Contract                          | 12-month contract (Enterprise)     | Pay-as-you-go, no lock-in                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |

## Key terminology mapping

If you're migrating from Heroku, the table below maps common Heroku concepts to their Aptible equivalents.

| Heroku Term     | Aptible Term                                                                            | Description                                             |
| --------------- | --------------------------------------------------------------------------------------- | ------------------------------------------------------- |
| Dyno            | [Container](/docs/core-concepts/architecture/containers/overview)                            | A running instance of your application process          |
| Heroku Router   | [Endpoint](/docs/core-concepts/apps/connecting-to-apps/app-endpoints/overview)               | Network entry point that routes traffic to your service |
| App URL         | Endpoint URL                                                                            | Public hostname exposing your service                   |
| Private Space   | [Dedicated Stack](/docs/core-concepts/architecture/stacks)                                   | Isolated infrastructure environment                     |
| Project         | [Environment](/docs/core-concepts/architecture/environments)                                 | Logical grouping of apps and databases                  |
| Config Vars     | [Environment Variables](/docs/core-concepts/apps/deploying-apps/configuration)               | Runtime configuration values                            |
| Buildpacks      | Dockerfile                                                                              | Defines how your application is built                   |
| Heroku Postgres | [Managed PostgreSQL](/docs/core-concepts/managed-databases/supported-databases/postgresql)   | Production database service                             |
| Heroku Redis    | [Managed Redis](/docs/core-concepts/managed-databases/supported-databases/redis)             | In-memory data store                                    |
| Add-ons         | [Managed Databases](/docs/core-concepts/managed-databases/overview) or External Integrations | Infrastructure services attached to your app            |

## Before you begin

Before starting your migration, ensure the following:

<Steps>
  <Step title="Create an Aptible account">
    [Sign up for Aptible](https://app.aptible.com/signup) to get started with a 30-day free trial. When you're ready to begin your production migration, upgrade to the Production plan.

    * **Development** is intended for early-stage development and testing, when you do not yet have production security or compliance requirements.
    * **Production** is designed for production workloads and provides access to highly secure and compliant resources, including support for frameworks such as [HIPAA](/docs/how-to-guides/platform-guides/hipaa-compliance).
  </Step>

  <Step title="Install the Aptible CLI">
    The CLI allows you to deploy applications, manage databases, and interact with your environment directly from your terminal.

    [Install the CLI here](/docs/reference/aptible-cli/overview).
  </Step>

  <Step title="Review your existing Heroku setup">
    Before migrating, make note of the following details from your existing Heroku setup:

    * Application process types (web, worker, background jobs)
    * Environment variables and secrets
    * Add-ons such as databases, caches, or third-party services
    * Any custom build or runtime configuration
    * Networking or domain configuration
  </Step>
</Steps>

## Migration steps

### Set up your Aptible infrastructure

#### Private Spaces to Dedicated Stacks

In Heroku, applications can run inside **Private Spaces**, which define the network boundary and isolation model for your workloads.

In Aptible, the equivalent concept is a [**Dedicated Stack**](/docs/core-concepts/architecture/stacks). A Dedicated Stack is an isolated AWS environment with its own VPC, enforced encryption, and infrastructure-level security controls.

<Steps>
  <Step title="Provision a Dedicated Stack">
    Create a Dedicated Stack in the appropriate region. If you need to support [HIPAA compliance](/docs/how-to-guides/platform-guides/hipaa-compliance), Dedicated Stacks are required.
  </Step>

  <Step title="Execute a BAA if required">
    During Stack provisioning, Aptible Support will coordinate execution of your Business Associate Agreement if you are handling PHI.
  </Step>

  <Step title="Review networking requirements">
    Confirm IP allowlists, outbound access, and any required third-party integrations. See [Network Integrations](/docs/core-concepts/integrations/network-integrations) for VPN and VPC peering options.
  </Step>
</Steps>

<Info>
  If you currently use multiple Private Spaces for staging and production, you can either:

  * Create separate Environments within a single Dedicated Stack (most common approach)
  * Provision multiple Dedicated Stacks if stricter infrastructure separation is required
</Info>

#### Projects to Environments

In Heroku, applications are grouped into **Projects** and can be connected via Pipelines.

In Aptible, applications and databases are grouped within an [**Environment**](/docs/core-concepts/architecture/environments), which exists inside a Dedicated Stack. An Environment provides logical separation between staging and production workloads and defines access controls.

* Create an Environment corresponding to each Heroku Project
* Create separate Environments for staging and production

<Tip>
  Granular user access is assigned at the Environment level. For example, you can grant full access to a staging Environment while restricting permissions in production.
</Tip>

### Migrate your application

#### Dynos to Containers

In Heroku, applications run as dynos built via buildpacks and defined by a Procfile. Heroku manages the runtime layer and abstracts containerization.

In Aptible, applications run as [Docker containers](/docs/core-concepts/architecture/containers/overview). You define how the application is built and executed using a Dockerfile, and each process type runs as its own service.

**Key differences:**

| Heroku                 | Aptible                                                                                              |
| ---------------------- | ---------------------------------------------------------------------------------------------------- |
| Buildpacks             | Dockerfile                                                                                           |
| Procfile process types | Separate [services](/docs/core-concepts/apps/deploying-apps/services)                                     |
| Dyno scaling           | Container scaling                                                                                    |
| Release phase          | Explicit release command via [.aptible.yml](/docs/core-concepts/apps/deploying-apps/releases/aptible-yml) |

<Steps>
  <Step title="Add a Dockerfile">
    If your app does not already use Docker, create a `Dockerfile`. See [Getting Started with Docker](/docs/how-to-guides/app-guides/getting-started-with-docker) for guidance.

    Example (Node.js):

    ```dockerfile theme={null}
    FROM node:18

    WORKDIR /app
    COPY package*.json ./
    RUN npm install

    COPY . .
    EXPOSE 3000
    CMD ["npm", "start"]
    ```

    Important checks:

    * App binds to `0.0.0.0`
    * Correct port exposed
    * No reliance on ephemeral filesystem storage
  </Step>

  <Step title="Translate Procfile process types">
    Typical Heroku Procfile:

    ```
    web: bundle exec rails server
    worker: bundle exec sidekiq
    release: bundle exec rails db:migrate
    ```

    In Aptible:

    * Deploy `web` as one service
    * Deploy `worker` as a separate service
    * Run database migrations using [before\_release](/docs/core-concepts/apps/deploying-apps/releases/aptible-yml) in `.aptible.yml`

    Each service can be scaled independently.

    Procfile and `.aptible.yml` placement depends on your deployment method:

    <Tabs>
      <Tab title="Deploying via Git">
        If you deploy by pushing code to Aptible's Git remote, keep your `Procfile` and `.aptible.yml` in the repository root directory. Aptible will detect and use them automatically during the build process.
      </Tab>

      <Tab title="Deploying via Docker image">
        If you deploy a pre-built image from a container registry, you must place these files inside the Docker image at:

        * `/.aptible/Procfile`
        * `/.aptible/.aptible.yml`

        See [`Procfiles and .aptible.yml when deploying via Docker image`](/docs/core-concepts/apps/deploying-apps/image/deploying-with-docker-image/procfile-aptible-yml-direct-docker-deploy) for details.
      </Tab>
    </Tabs>
  </Step>

  <Step title="Configure environment variables">
    Export your current Heroku variables:

    ```bash theme={null}
    heroku config --app your-app-name
    ```

    Recreate them in the Aptible Environment using the Dashboard or CLI:

    ```bash theme={null}
    aptible config:set --app your-app-name KEY=value
    ```

    Pay special attention to:

    * `DATABASE_URL`
    * `REDIS_URL`
    * `SECRET_KEY_BASE`
    * External service credentials

    See [Configuration Variables](/docs/core-concepts/apps/deploying-apps/configuration) for more details.
  </Step>

  <Step title="Scale containers">
    Match your dyno configuration. If you previously ran 2 web dynos and 1 worker dyno, scale to 2 web containers and 1 worker container.

    ```bash theme={null}
    aptible apps:scale --app your-app-name --container-count 2 SERVICE
    ```

    Monitor CPU and memory usage after deployment and adjust as needed. See [App Scaling](/docs/core-concepts/scaling/app-scaling) for guidance.
  </Step>

  <Step title="Validate deployment">
    Confirm:

    * Application boots without errors
    * Logs are flowing
    * Health checks pass
    * Background jobs process correctly
    * No reliance on Heroku-specific environment assumptions
  </Step>
</Steps>

### Migrate your databases

Heroku provides Heroku Postgres and Heroku Redis.

In Aptible, you can provision [managed PostgreSQL](/docs/core-concepts/managed-databases/supported-databases/postgresql), [Redis](/docs/core-concepts/managed-databases/supported-databases/redis), as well as [MySQL](/docs/core-concepts/managed-databases/supported-databases/mysql), [Elasticsearch](/docs/core-concepts/managed-databases/supported-databases/elasticsearch), [InfluxDB](/docs/core-concepts/managed-databases/supported-databases/influxdb), [RabbitMQ](/docs/core-concepts/managed-databases/supported-databases/rabbitmq), and [SFTP](/docs/core-concepts/managed-databases/supported-databases/sftp).

#### Migrating PostgreSQL

There are two primary approaches to migrating PostgreSQL databases:

* **Dump and restore** works well for smaller databases (under 10GB) and simpler migrations
* **Logical replication** is recommended for databases over 10GB or high-traffic production apps where minimizing downtime is critical

<Tip>
  For databases larger than 10GB, `heroku pg:backups` can be slow and unreliable. Logical replication keeps your Aptible database in sync with Heroku until you're ready to cut over, significantly reducing downtime.
</Tip>

<AccordionGroup>
  <Accordion title="Option A: Dump and Restore (recommended for databases under 10GB)">
    <Steps>
      <Step title="Capture backup from Heroku">
        ```bash theme={null}
        heroku pg:backups:capture --app your-app-name
        heroku pg:backups:download --app your-app-name
        ```

        For large databases:

        * Schedule a maintenance window
        * Consider putting the application in read-only mode
        * Lower DNS TTL in advance if planning cutover
      </Step>

      <Step title="Provision PostgreSQL in Aptible">
        Create a managed PostgreSQL database in the target Environment:

        ```bash theme={null}
        aptible db:create your-database \
          --type postgresql \
          --version 16 \
          --environment your-environment
        ```

        * Confirm version compatibility with Heroku Postgres
        * Verify required extensions are supported

        See [PostgreSQL documentation](/docs/core-concepts/managed-databases/supported-databases/postgresql) for supported versions and extensions.
      </Step>

      <Step title="Restore database">
        Open a tunnel to your new database:

        ```bash theme={null}
        aptible db:tunnel your-database --environment your-environment
        ```

        In a separate terminal, restore the backup:

        ```bash theme={null}
        pg_restore --verbose --clean --no-acl --no-owner \
          -h localhost \
          -p PORT \
          -U aptible \
          -d db \
          latest.dump
        ```

        For large restores, use `--jobs=N` for parallel restore.

        See [Dump and Restore PostgreSQL](/docs/how-to-guides/database-guides/dump-restore-postgresql) for detailed instructions.
      </Step>

      <Step title="Update DATABASE_URL">
        Replace Heroku credentials with the Aptible database credentials:

        ```bash theme={null}
        aptible config:set --app your-app-name DATABASE_URL=postgresql://...
        ```

        Confirm SSL mode is correct and update connection pooling configuration if used.
      </Step>

      <Step title="Validate database">
        * Compare row counts
        * Verify schema
        * Confirm extensions such as `pgcrypto` or `uuid-ossp`
        * Run the application against the staging database
        * Monitor logs for connection errors
      </Step>
    </Steps>
  </Accordion>

  <Accordion title="Option B: Logical Replication (recommended for databases over 10GB)">
    Logical replication keeps your Aptible database in sync with your Heroku database until you cut over. This minimizes downtime for high-traffic production applications.

    <Steps>
      <Step title="Provision PostgreSQL in Aptible">
        Create a managed PostgreSQL database in the target Environment:

        ```bash theme={null}
        aptible db:create your-database \
          --type postgresql \
          --version 16 \
          --environment your-environment
        ```

        Match the PostgreSQL version to your Heroku database. See [PostgreSQL documentation](/docs/core-concepts/managed-databases/supported-databases/postgresql) for supported versions.
      </Step>

      <Step title="Set up logical replication">
        Use the Aptible CLI to create a logical replica that syncs from your Heroku database:

        ```bash theme={null}
        aptible db:replicate heroku-source-db aptible-replica \
          --logical --version 16
        ```

        This uses the `pglogical` extension to replicate data from Heroku to Aptible. The replica stays in sync until you're ready to cut over.

        See [Database Replication](/docs/core-concepts/managed-databases/managing-databases/replication-clustering) and [`aptible db:replicate`](/docs/reference/aptible-cli/cli-commands/cli-db-replicate) for details.
      </Step>

      <Step title="Monitor replication status">
        Verify that all tables have finished the initial sync:

        ```sql theme={null}
        SELECT * FROM pglogical.local_sync_status WHERE NOT sync_status = 'r';
        ```

        An empty result means all tables are fully replicated.
      </Step>

      <Step title="Cut over">
        When ready to cut over:

        1. Stop writes to the Heroku database
        2. Verify replication is caught up
        3. Update `DATABASE_URL` to point to Aptible
        4. Switch DNS to Aptible
      </Step>
    </Steps>
  </Accordion>
</AccordionGroup>

#### Migrating Redis

<Steps>
  <Step title="Provision Redis in Aptible">
    Create a managed Redis instance:

    ```bash theme={null}
    aptible db:create your-redis \
      --type redis \
      --environment your-environment
    ```

    Confirm version compatibility. See [Redis documentation](/docs/core-concepts/managed-databases/supported-databases/redis).
  </Step>

  <Step title="Update REDIS_URL">
    Update the environment variable in Aptible:

    ```bash theme={null}
    aptible config:set --app your-app-name REDIS_URL=redis://...
    ```
  </Step>

  <Step title="Plan cutover">
    If Redis is used as:

    * **Cache only**: No data migration required
    * **Job queue**: Coordinate cutover carefully to avoid dropped jobs
  </Step>

  <Step title="Validate">
    * Confirm application connectivity
    * Monitor background worker logs
    * Validate job processing
  </Step>
</Steps>

### Audit your add-ons

Before migrating, review all add-ons attached to your Heroku application:

```bash theme={null}
heroku addons --app your-app-name
```

Typical mappings:

| Heroku Add-on                      | Migration Approach                                                                                                                |
| ---------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- |
| Heroku Postgres                    | Migrate to [Aptible-managed PostgreSQL](/docs/core-concepts/managed-databases/supported-databases/postgresql)                          |
| Heroku Redis                       | Migrate to [Aptible-managed Redis](/docs/core-concepts/managed-databases/supported-databases/redis)                                    |
| Logging add-ons (e.g., Papertrail) | Configure [log drains](/docs/core-concepts/observability/logs/log-drains/overview) to your observability provider (no additional cost) |
| Email providers                    | Continue using external provider and update credentials                                                                           |
| Third-party services               | Reconfigure networking and environment variables                                                                                  |

### Configure endpoints and networking

In Heroku, applications are exposed via the Heroku Router.

In Aptible, applications are exposed through explicitly defined [**Endpoints**](/docs/core-concepts/apps/connecting-to-apps/app-endpoints/overview).

#### Public Endpoints

If your application is publicly accessible:

* Create a Public Endpoint for the service
* Attach your [custom domain](/docs/core-concepts/apps/connecting-to-apps/app-endpoints/custom-domain)
* Confirm [TLS configuration](/docs/core-concepts/apps/connecting-to-apps/app-endpoints/managed-tls)
* Validate [IP allowlists](/docs/core-concepts/apps/connecting-to-apps/app-endpoints/ip-filtering) if required

#### Private Endpoints

If your Heroku Private Space uses internal routing between services:

* Create Private Endpoints inside the Dedicated Stack
* Update internal service URLs
* Confirm security group or access configuration

#### Networking checklist

* Review [outbound IP requirements](/docs/core-concepts/apps/connecting-to-apps/outbound-ips)
* Confirm third-party allowlists
* Update webhook destinations if needed
* Verify internal service-to-service communication

<Info>
  Networking differences are often the largest architectural shift when moving to a dedicated infrastructure model. Take time to review your requirements carefully.
</Info>

### Minimize downtime during cutover

To reduce downtime and risk during migration, plan the final cutover carefully.

<Steps>
  <Step title="Deploy and validate in staging">
    Deploy and validate your application in Aptible staging. Perform database migration to staging and test thoroughly.
  </Step>

  <Step title="Lower DNS TTL">
    Lower DNS TTL at least 24 hours before cutover to enable faster DNS propagation.
  </Step>

  <Step title="Schedule maintenance window">
    Schedule a maintenance window if required for your application.
  </Step>

  <Step title="Take final backup">
    Take a final database backup immediately before cutover:

    ```bash theme={null}
    heroku pg:backups:capture --app your-app-name
    ```
  </Step>

  <Step title="Restore final backup">
    Restore the final backup to your Aptible production database.
  </Step>

  <Step title="Update environment variables">
    Update environment variables to point to the new database.
  </Step>

  <Step title="Switch DNS">
    Switch DNS to the Aptible Endpoint.
  </Step>

  <Step title="Monitor">
    Monitor logs, performance, and background workers.
  </Step>
</Steps>

<Warning>
  **Additional considerations:**

  * If Redis is used as a job queue, pause workers before final backup
  * Confirm no writes occur between final backup and DNS switch
  * Keep the Heroku app available briefly as a fallback if necessary
</Warning>

After confirming stable traffic and application behavior, decommission your Heroku resources.

## Closing thoughts

Once your migration is complete, your workloads run on a platform designed for security, compliance, and long-term scalability. By carefully planning your infrastructure mapping, database migration, and cutover strategy, you can transition with minimal disruption.

If you need guidance during your migration, [Aptible Support](https://app.aptible.com/support) is available to help. White-glove migration services are also available for teams that want hands-on assistance.


# Heroku Shield to Aptible Migration Guide
Source: https://www.aptible.com/docs/how-to-guides/platform-guides/heroku-shield-migration

A comprehensive guide for migrating compliance-focused applications from Heroku Shield to Aptible

## Overview

If you are searching for a Heroku Shield alternative, Aptible is one of the strongest platform-as-a-service options to evaluate, and for many regulated teams, the most natural fit.

Aptible delivers a similar developer experience with simple, abstracted deployment of apps and databases, while providing dedicated infrastructure isolation, enforced security controls, and built-in compliance support for frameworks such as HIPAA, HITRUST, and SOC 2. For teams handling PHI or other sensitive data, these controls are foundational, not optional.

[**Refer to the Security & Compliance docs for more information on our approach to security and compliance, including the specific controls we satisfy.**](/docs/core-concepts/security-compliance/overview)

If you are evaluating alternatives due to[ recent changes to Heroku’s Enterprise offering](https://www.heroku.com/blog/an-update-on-heroku/), you're in the right place. Many teams that previously relied on Heroku Shield for HIPAA-eligible environments are now looking for infrastructure that combines developer simplicity with robust security and compliance support.

This guide will help you evaluate Aptible and outline a clear path for a smooth migration, including:

* Heroku Shield vs Aptible comparison
* Key terminology mapping
* Technical migration steps:
  * Private Spaces to Dedicated Stacks
  * Projects to Environments
  * Shield dynos to containers
  * Shield Postgres and Redis to Aptible-managed databases
  * Auditing Shield-compatible add-ons
  * Reconfiguring endpoints and networking
  * Minimizing downtime during cutover

<Tip>
  If you're migrating from standard Heroku (not Shield), see the [general Heroku migration guide](/docs/how-to-guides/platform-guides/heroku-migration).
</Tip>

<Tip>
  If you require further assistance or guidance during your migration, please [contact Aptible Support](https://app.aptible.com/support). White-glove migration services are also available for teams that want hands-on assistance.
</Tip>

## FAQs

<AccordionGroup>
  <Accordion title="Why migrate from Heroku Shield to Aptible?">
    Aptible is a security, compliance, and reliability-focused platform as a service (PaaS). Migrating to Aptible enables you to maintain a strong compliance posture with built-in support for frameworks such as HIPAA, HITRUST, and SOC 2, while gaining more flexibility in pricing and operational control.

    Teams typically migrate from Heroku Shield when they need HITRUST inheritance, more flexible pricing, or want to avoid 12-month contract commitments while maintaining the same level of compliance.
  </Accordion>

  <Accordion title="How does Aptible pricing compare to Heroku Shield?">
    If you're migrating from Heroku Shield, Aptible differs in two important ways: Aptible does not require a 12-month contract, and Aptible does not enforce high minimum spend thresholds. This makes it easier to adopt without long-term financial commitments.

    Aptible's pricing model is usage-based with simple line items and no long-term lock-ins or steep minimums.

    [Learn more about pricing](/docs/reference/pricing).
  </Accordion>

  <Accordion title="Can I keep using a Procfile?">
    Yes. Heroku requires a Procfile to define application processes, but on Aptible, Procfiles are optional.

    If no Procfile is present, Aptible will infer the service command from the Dockerfile `CMD` instruction. This is referred to as an [Implicit Service](/docs/how-to-guides/app-guides/define-services#how-to-define-services).

    You can continue using a Procfile if your application has multiple services or process types. Procfile syntax is compatible between Heroku and Aptible.

    **Note:** If you are [deploying via Docker image](/docs/how-to-guides/app-guides/migrate-dockerfile-to-direct-image-deploy) (deploying a pre-built image from a container registry), you must place your Procfile at `/.aptible/Procfile` and your `.aptible.yml` at `/.aptible/.aptible.yml` inside your Docker image. See [`Procfiles and .aptible.yml when deploying via Docker image`](/docs/core-concepts/apps/deploying-apps/image/deploying-with-docker-image/procfile-aptible-yml-direct-docker-deploy) for details.
  </Accordion>
</AccordionGroup>

## Heroku Shield vs Aptible comparison

The table below summarizes key differences across compliance, developer experience, and pricing.

| Category                          | Heroku Shield                      | Aptible                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| --------------------------------- | ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Compliance**                    |                                    |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| HIPAA Eligibility                 | Included                           | Included                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| HITRUST Inheritance               | Not available                      | Included                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| BAA Support                       | Included                           | Included                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| Encryption in Transit and at Rest | Included                           | Included, by default                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| Managed Intrusion Detection       | Not available                      | Included, by default                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| 24/7 SRE Monitoring               | Available with additional fee      | Included, by default                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| Automated Backups                 | Included, plan-dependent retention | Included, by default                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| Granular Access Control           | Limited                            | Included, by default                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| Infrastructure Isolation          | Included (Private Spaces)          | Included ([Dedicated Stacks](/docs/core-concepts/architecture/stacks))                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| **Developer Experience**          |                                    |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| Runtime Model                     | Dynos                              | [Docker containers](/docs/core-concepts/architecture/containers/overview)                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| Build System                      | Buildpacks                         | Dockerfile-based                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| Traffic Routing                   | Heroku Router                      | Explicit [Endpoints](/docs/core-concepts/apps/connecting-to-apps/app-endpoints/overview)                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| Automatic Rollbacks               | Limited                            | Included, by default                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| Zero-downtime deploys             | Included, by default               | Included, by default                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| Public and Private Access         | Limited                            | Available (Public and Private [Endpoints](/docs/core-concepts/apps/connecting-to-apps/app-endpoints/overview) supported)                                                                                                                                                                                                                                                                                                                                                                                                                   |
| Managed Databases                 | Shield Postgres & Shield Redis     | [PostgreSQL](/docs/core-concepts/managed-databases/supported-databases/postgresql), [MySQL](/docs/core-concepts/managed-databases/supported-databases/mysql), [Redis](/docs/core-concepts/managed-databases/supported-databases/redis), [Elasticsearch](/docs/core-concepts/managed-databases/supported-databases/elasticsearch), [RabbitMQ](/docs/core-concepts/managed-databases/supported-databases/rabbitmq), [InfluxDB](/docs/core-concepts/managed-databases/supported-databases/influxdb), [SFTP](/docs/core-concepts/managed-databases/supported-databases/sftp) |
| **Pricing**                       |                                    |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| Compute Pricing Model             | Shield dyno tiers                  | Container-based pricing                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| Isolation Cost                    | High fees for getting started      | Low fees for getting started: \$499/base fee                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| Contract                          | 12-month contract required         | Pay-as-you-go, no lock-in                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| White-glove migration             | Not available                      | Available with additional fee                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |

## Key terminology mapping

If you're migrating from Heroku Shield, the table below maps common Heroku concepts to their Aptible equivalents.

| Heroku Term     | Aptible Term                                                                            | Description                                             |
| --------------- | --------------------------------------------------------------------------------------- | ------------------------------------------------------- |
| Dyno            | [Container](/docs/core-concepts/architecture/containers/overview)                            | A running instance of your application process          |
| Heroku Router   | [Endpoint](/docs/core-concepts/apps/connecting-to-apps/app-endpoints/overview)               | Network entry point that routes traffic to your service |
| App URL         | Endpoint URL                                                                            | Public hostname exposing your service                   |
| Private Space   | [Dedicated Stack](/docs/core-concepts/architecture/stacks)                                   | Isolated infrastructure environment                     |
| Project         | [Environment](/docs/core-concepts/architecture/environments)                                 | Logical grouping of apps and databases                  |
| Config Vars     | [Environment Variables](/docs/core-concepts/apps/deploying-apps/configuration)               | Runtime configuration values                            |
| Buildpacks      | Dockerfile                                                                              | Defines how your application is built                   |
| Shield Postgres | [Managed PostgreSQL](/docs/core-concepts/managed-databases/supported-databases/postgresql)   | Production database service                             |
| Shield Redis    | [Managed Redis](/docs/core-concepts/managed-databases/supported-databases/redis)             | In-memory data store                                    |
| Add-ons         | [Managed Databases](/docs/core-concepts/managed-databases/overview) or External Integrations | Infrastructure services attached to your app            |

## Before you begin

Before starting your migration from Heroku Shield, ensure the following:

<Steps>
  <Step title="Create an Aptible account">
    [Sign up for Aptible](https://app.aptible.com/signup) to get started with a 30-day free trial. When you're ready to begin your production migration, upgrade to the Production plan.
  </Step>

  <Step title="Install the Aptible CLI">
    The CLI allows you to deploy applications, manage databases, and interact with your environment directly from your terminal.

    [Install the CLI here](/docs/reference/aptible-cli/overview).
  </Step>

  <Step title="Review your existing Heroku Shield setup">
    Ensure you have access to your Heroku app, Private Space, and Shield Postgres credentials. Make note of the following:

    * Application process types (web, worker, background jobs)
    * Environment variables and secrets
    * Add-ons such as databases, caches, or third-party services
    * Any custom build or runtime configuration
    * Networking or domain configuration
  </Step>
</Steps>

## Migration steps

### Set up your Aptible infrastructure

#### Private Spaces to Dedicated Stacks

In Heroku Shield, applications run inside **Private Spaces**, which define the network boundary and isolation model for your workloads.

In Aptible, the equivalent concept is a [**Dedicated Stack**](/docs/core-concepts/architecture/stacks). A Dedicated Stack is an isolated AWS environment with its own VPC, enforced encryption, and infrastructure-level security controls.

<Steps>
  <Step title="Provision a Dedicated Stack">
    Create a Dedicated Stack in the appropriate region. Dedicated Stacks are required for [HIPAA compliance](/docs/how-to-guides/platform-guides/hipaa-compliance).
  </Step>

  <Step title="Execute a BAA if required">
    During Stack provisioning, Aptible Support will coordinate execution of your Business Associate Agreement if you are handling PHI.
  </Step>

  <Step title="Review networking requirements">
    Confirm IP allowlists, outbound access, and any required third-party integrations. See [Network Integrations](/docs/core-concepts/integrations/network-integrations) for fVPN and VPC peering options.
  </Step>
</Steps>

<Info>
  If you currently use multiple Private Spaces for staging and production, you can either:

  * Create separate Environments within a single Dedicated Stack (most common approach)
  * Provision multiple Dedicated Stacks if stricter infrastructure separation is required

  Choose the approach that aligns with your compliance and isolation requirements.
</Info>

#### Projects to Environments

In Heroku, applications are grouped into **Projects** and can be connected via Pipelines.

In Aptible, applications and databases are grouped within an [**Environment**](/docs/core-concepts/architecture/environments), which exists inside a Dedicated Stack. An Environment provides logical separation between staging and production workloads and defines access controls.

* Create an Environment corresponding to each Heroku Project
* Create separate Environments for staging and production

<Tip>
  Granular user access is assigned at the Environment level. For example, you can grant full access to a staging Environment while restricting permissions in production.
</Tip>

### Migrate your application

### Shield Dynos to Containers

In Heroku Shield, applications run as dynos built via buildpacks and defined by a Procfile. Heroku manages the runtime layer and abstracts containerization.

In Aptible, applications run as [Docker containers](/docs/core-concepts/architecture/containers/overview). You define how the application is built and executed using a Dockerfile, and each process type runs as its own service.

**Key differences:**

| Heroku Shield          | Aptible                                                                                              |
| ---------------------- | ---------------------------------------------------------------------------------------------------- |
| Buildpacks             | Dockerfile                                                                                           |
| Procfile process types | Separate [services](/docs/core-concepts/apps/deploying-apps/services)                                     |
| Dyno scaling           | Container scaling                                                                                    |
| Release phase          | Explicit release command via [.aptible.yml](/docs/core-concepts/apps/deploying-apps/releases/aptible-yml) |

<Steps>
  <Step title="Convert Buildpack App to Docker">
    If your app does not already use Docker, create a `Dockerfile`. See [Getting Started with Docker](/docs/how-to-guides/app-guides/getting-started-with-docker) for guidance.

    Example (Node.js):

    ```dockerfile theme={null}
    FROM node:18

    WORKDIR /app
    COPY package*.json ./
    RUN npm install

    COPY . .
    EXPOSE 3000
    CMD ["npm", "start"]
    ```

    Important checks:

    * App binds to `0.0.0.0`
    * Correct port exposed
    * No reliance on ephemeral filesystem storage
  </Step>

  <Step title="Translate Procfile process types">
    Typical Heroku Procfile:

    ```
    web: bundle exec rails server
    worker: bundle exec sidekiq
    release: bundle exec rails db:migrate
    ```

    In Aptible:

    * Deploy `web` as one service
    * Deploy `worker` as a separate service
    * Run database migrations using [before\_release](/docs/core-concepts/apps/deploying-apps/releases/aptible-yml) in `.aptible.yml`

    Each service can be scaled independently.

    Procfile and `.aptible.yml` placement depends on your deployment method:

    <Tabs>
      <Tab title="Deploying via Git">
        If you deploy by pushing code to Aptible's Git remote, keep your `Procfile` and `.aptible.yml` in the repository root directory. Aptible will detect and use them automatically during the build process.
      </Tab>

      <Tab title="Deploying via Docker image">
        If you deploy a pre-built image from a container registry, you must place these files inside the Docker image at:

        * `/.aptible/Procfile`
        * `/.aptible/.aptible.yml`

        See [`Procfiles and .aptible.yml when deploying via Docker image`](/docs/core-concepts/apps/deploying-apps/image/deploying-with-docker-image/procfile-aptible-yml-direct-docker-deploy) for details.
      </Tab>
    </Tabs>
  </Step>

  <Step title="Configure environment variables">
    Export your current Heroku variables:

    ```bash theme={null}
    heroku config --app your-app-name
    ```

    Recreate them in the Aptible Environment using the Dashboard or CLI:

    ```bash theme={null}
    aptible config:set --app your-app-name KEY=value
    ```

    Pay special attention to:

    * `DATABASE_URL`
    * `REDIS_URL`
    * `SECRET_KEY_BASE`
    * External service credentials

    See [Configuration Variables](/docs/core-concepts/apps/deploying-apps/configuration) for more details.
  </Step>

  <Step title="Scale containers">
    Match your dyno configuration. If you previously ran 2 web dynos and 1 worker dyno, scale to 2 web containers and 1 worker container.

    ```bash theme={null}
    aptible apps:scale --app your-app-name --container-count 2 SERVICE
    ```

    Monitor CPU and memory usage after deployment and adjust as needed. See [App Scaling](/docs/core-concepts/scaling/app-scaling) for guidance.
  </Step>

  <Step title="Validate deployment">
    Confirm:

    * Application boots without errors
    * Logs are flowing
    * Health checks pass
    * Background jobs process correctly
    * No reliance on Heroku-specific environment assumptions
  </Step>
</Steps>

### Migrate your databases

Heroku Shield provides Shield Postgres and Shield Redis inside your Private Space with encryption and compliance controls.

In Aptible, you can provision [managed PostgreSQL](/docs/core-concepts/managed-databases/supported-databases/postgresql), [Redis](/docs/core-concepts/managed-databases/supported-databases/redis), as well as [MySQL](/docs/core-concepts/managed-databases/supported-databases/mysql), [Elasticsearch](/docs/core-concepts/managed-databases/supported-databases/elasticsearch), [InfluxDB](/docs/core-concepts/managed-databases/supported-databases/influxdb), [RabbitMQ](/docs/core-concepts/managed-databases/supported-databases/rabbitmq), and [SFTP](/docs/core-concepts/managed-databases/supported-databases/sftp).

#### Migrating PostgreSQL

There are two primary approaches to migrating PostgreSQL databases:

* **Dump and restore** works well for smaller databases (under 10GB) and simpler migrations
* **Logical replication** is recommended for databases over 10GB or high-traffic production apps where minimizing downtime is critical

<Tip>
  For databases larger than 10GB, `heroku pg:backups` can be slow and unreliable. Logical replication keeps your Aptible database in sync with Heroku until you're ready to cut over, significantly reducing downtime.
</Tip>

<AccordionGroup>
  <Accordion title="Option A: Dump and Restore (recommended for databases under 10GB)">
    <Steps>
      <Step title="Capture backup from Heroku">
        ```bash theme={null}
        heroku pg:backups:capture --app your-app-name
        heroku pg:backups:download --app your-app-name
        ```

        For large databases:

        * Schedule a maintenance window
        * Consider putting the application in read-only mode
        * Lower DNS TTL in advance if planning cutover
      </Step>

      <Step title="Provision PostgreSQL in Aptible">
        Create a managed PostgreSQL database in the target Environment:

        ```bash theme={null}
        aptible db:create your-database \
          --type postgresql \
          --version 16 \
          --environment your-environment
        ```

        * Confirm version compatibility with Heroku Postgres
        * Verify required extensions are supported

        See [PostgreSQL documentation](/docs/core-concepts/managed-databases/supported-databases/postgresql) for supported versions and extensions.
      </Step>

      <Step title="Restore database">
        Open a tunnel to your new database:

        ```bash theme={null}
        aptible db:tunnel your-database --environment your-environment
        ```

        In a separate terminal, restore the backup:

        ```bash theme={null}
        pg_restore --verbose --clean --no-acl --no-owner \
          -h localhost \
          -p PORT \
          -U aptible \
          -d db \
          latest.dump
        ```

        For large restores, use `--jobs=N` for parallel restore.

        See [Dump and Restore PostgreSQL](/docs/how-to-guides/database-guides/dump-restore-postgresql) for detailed instructions.
      </Step>

      <Step title="Update DATABASE_URL">
        Replace Heroku credentials with the Aptible database credentials:

        ```bash theme={null}
        aptible config:set --app your-app-name DATABASE_URL=postgresql://...
        ```

        Confirm SSL mode is correct and update connection pooling configuration if used.
      </Step>

      <Step title="Validate database">
        * Compare row counts
        * Verify schema
        * Confirm extensions such as `pgcrypto` or `uuid-ossp`
        * Run the application against the staging database
        * Monitor logs for connection errors
      </Step>
    </Steps>
  </Accordion>

  <Accordion title="Option B: Logical Replication (recommended for databases over 10GB)">
    Logical replication keeps your Aptible database in sync with your Heroku database until you cut over. This minimizes downtime for high-traffic production applications.

    <Steps>
      <Step title="Provision PostgreSQL in Aptible">
        Create a managed PostgreSQL database in the target Environment:

        ```bash theme={null}
        aptible db:create your-database \
          --type postgresql \
          --version 16 \
          --environment your-environment
        ```

        Match the PostgreSQL version to your Heroku database. See [PostgreSQL documentation](/docs/core-concepts/managed-databases/supported-databases/postgresql) for supported versions.
      </Step>

      <Step title="Set up logical replication">
        Use the Aptible CLI to create a logical replica that syncs from your Heroku database:

        ```bash theme={null}
        aptible db:replicate heroku-source-db aptible-replica \
          --logical --version 16
        ```

        This uses the `pglogical` extension to replicate data from Heroku to Aptible. The replica stays in sync until you're ready to cut over.

        See [Database Replication](/docs/core-concepts/managed-databases/managing-databases/replication-clustering) and [`aptible db:replicate`](/docs/reference/aptible-cli/cli-commands/cli-db-replicate) for details.
      </Step>

      <Step title="Monitor replication status">
        Verify that all tables have finished the initial sync:

        ```sql theme={null}
        SELECT * FROM pglogical.local_sync_status WHERE NOT sync_status = 'r';
        ```

        An empty result means all tables are fully replicated.
      </Step>

      <Step title="Cut over">
        When ready to cut over:

        1. Stop writes to the Heroku database
        2. Verify replication is caught up
        3. Update `DATABASE_URL` to point to Aptible
        4. Switch DNS to Aptible
      </Step>
    </Steps>
  </Accordion>
</AccordionGroup>

#### Migrating Redis

<Steps>
  <Step title="Provision Redis in Aptible">
    Create a managed Redis instance:

    ```bash theme={null}
    aptible db:create your-redis \
      --type redis \
      --environment your-environment
    ```

    Confirm version compatibility. See [Redis documentation](/docs/core-concepts/managed-databases/supported-databases/redis).
  </Step>

  <Step title="Update REDIS_URL">
    Update the environment variable in Aptible:

    ```bash theme={null}
    aptible config:set --app your-app-name REDIS_URL=redis://...
    ```
  </Step>

  <Step title="Plan cutover">
    If Redis is used as:

    * **Cache only**: No data migration required
    * **Job queue**: Coordinate cutover carefully to avoid dropped jobs
  </Step>

  <Step title="Validate">
    * Confirm application connectivity
    * Monitor background worker logs
    * Validate job processing
  </Step>
</Steps>

### Auditing your add-ons

Before migrating, review all add-ons attached to your Heroku Shield application:

```bash theme={null}
heroku addons --app your-app-name
```

Typical mappings:

| Heroku Add-on                      | Migration Approach                                                                                                                |
| ---------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- |
| Shield Postgres                    | Migrate to [Aptible-managed PostgreSQL](/docs/core-concepts/managed-databases/supported-databases/postgresql)                          |
| Shield Redis                       | Migrate to [Aptible-managed Redis](/docs/core-concepts/managed-databases/supported-databases/redis)                                    |
| Logging add-ons (e.g., Papertrail) | Configure [log drains](/docs/core-concepts/observability/logs/log-drains/overview) to your observability provider (no additional cost) |
| Email providers                    | Continue using external provider and update credentials                                                                           |
| Third-party services               | Reconfigure networking and environment variables                                                                                  |

### Configuring endpoints and networking

In Heroku Shield, applications are exposed via the Heroku Router within a Private Space.

In Aptible, applications are exposed through explicitly defined [**Endpoints**](/docs/core-concepts/apps/connecting-to-apps/app-endpoints/overview).

#### Public Endpoints

If your application is publicly accessible:

* Create a Public Endpoint for the service
* Attach your [custom domain](/docs/core-concepts/apps/connecting-to-apps/app-endpoints/custom-domain)
* Confirm [TLS configuration](/docs/core-concepts/apps/connecting-to-apps/app-endpoints/managed-tls)
* Validate [IP allowlists](/docs/core-concepts/apps/connecting-to-apps/app-endpoints/ip-filtering) if required

#### Private Endpoints

If your Heroku Private Space uses internal routing between services:

* Create Private Endpoints inside the Dedicated Stack
* Update internal service URLs
* Confirm security group or access configuration

#### Networking checklist

* Review [outbound IP requirements](/docs/core-concepts/apps/connecting-to-apps/outbound-ips)
* Confirm third-party allowlists
* Update webhook destinations if needed
* Verify internal service-to-service communication

<Info>
  Networking differences are often the largest architectural shift when moving from Shield to a dedicated infrastructure model. Take time to review your requirements carefully.
</Info>

### Minimizing downtime during cutover

To reduce downtime and risk during migration, plan the final cutover carefully.

<Steps>
  <Step title="Deploy and validate in staging">
    Deploy and validate your application in Aptible staging. Perform database migration to staging and test thoroughly.
  </Step>

  <Step title="Lower DNS TTL">
    Lower DNS TTL at least 24 hours before cutover to enable faster DNS propagation.
  </Step>

  <Step title="Schedule maintenance window">
    Schedule a maintenance window if required for your application.
  </Step>

  <Step title="Take final backup">
    Take a final database backup immediately before cutover:

    ```bash theme={null}
    heroku pg:backups:capture --app your-app-name
    ```
  </Step>

  <Step title="Restore final backup">
    Restore the final backup to your Aptible production database.
  </Step>

  <Step title="Update environment variables">
    Update environment variables to point to the new database.
  </Step>

  <Step title="Switch DNS">
    Switch DNS to the Aptible Endpoint.
  </Step>

  <Step title="Monitor">
    Monitor logs, performance, and background workers.
  </Step>
</Steps>

<Warning>
  **Additional considerations:**

  * If Redis is used as a job queue, pause workers before final backup
  * Confirm no writes occur between final backup and DNS switch
  * Keep the Heroku app available briefly as a fallback if necessary
</Warning>

After confirming stable traffic and application behavior, decommission your Heroku Shield resources.

## Closing thoughts

For most teams, migrating from Heroku Shield to Aptible is a same-day process. The core steps are mapping your infrastructure, migrating your databases, and executing a cutover strategy with minimal disruption.

Once complete, your regulated workloads run on a platform designed for security and compliance. If you need guidance during your migration, [contact Aptible Support](https://app.aptible.com/support). White-glove migration services are also available for teams seeking hands-on assistance.


# How to achieve HIPAA compliance on Aptible
Source: https://www.aptible.com/docs/how-to-guides/platform-guides/hipaa-compliance

Learn how to achieve HIPAA compliance on Aptible, the leading platform for hosting HIPAA-compliant apps & databases

## Overview

[Aptible's story](/docs/getting-started/introduction#our-story) began with a focus on serving digital health companies. As a result, the Aptible platform was designed with HIPAA compliance in mind. It automates and enforces all the necessary infrastructure security and compliance controls, ensuring the safe storage and processing of HIPAA-protected health information and more.

This guide will cover the essential steps for achieving HIPAA compliance on Aptible.

## HIPAA-Compliant Production Checklist

> Prerequisites: An Aptible account on Production or Enterprise plan.

1. **Provision a dedicated stack**

   1. [Dedicated stacks](/docs/core-concepts/architecture/stacks#dedicated-stacks) live on isolated infrastructure and are designed to support deploying resources with higher requirements— such as HIPAA. Aptible automates and enforces **100%** of the necessary infrastructure security and compliance controls for HIPAA compliance. This includes but is not limited to:

      1. Network Segregation (see: [stacks](/docs/core-concepts/architecture/stacks#dedicated-stacks))

      2. Platform Activity Logging (see: [activity](/docs/core-concepts/observability/activity/overview))

      3. Automated Backups & Automated Backup Testing (see: [database backups](/docs/core-concepts/managed-databases/managing-databases/database-backups))

      4. Database Encryption at Rest (see: [database encryption](/docs/core-concepts/managed-databases/managing-databases/database-encryption/overview))

      5. End-to-end Encryption in Transit (see: [database encryption](/docs/core-concepts/managed-databases/managing-databases/database-encryption/overview))

      6. DDoS Protection (see: [DDoS Protection](/docs/core-concepts/security-compliance/ddos-pid-limits))

      7. Automatic Container Recovery (see: [container recovery](/docs/core-concepts/architecture/containers/container-recovery))

      8. Intrusion Detection (see: [HIDS](/docs/core-concepts/security-compliance/hids))

      9. Host Hardening

      10. Secure Infrastructure Access, Development, and Testing Practices

      11. 24/7 Site Reliability and Incident Response

      12. Infrastructure Penetration Tested

2. **Execute a BAA with Aptible**

   1. When you request your first dedicated stack, an Aptible team member will reach out to coordinate the execution of a Business Associate Agreement (BAA).

**After these steps are taken, you are ready to process PHI! 🎉**

Here are some optional steps you can take:

1. Review your [Security & Compliance Dashboard](/docs/core-concepts/security-compliance/security-compliance-dashboard)

   1. Review the controls implemented for you, enhance your security posture by implementing additional controls, and share a detailed report with your customers.

2. Show off your compliance with a Secured by Aptible HIPAA compliance badge<img alt="" />

3. Set up log retention

   1. Set up long-term log retention with the use of a [log drain](/docs/core-concepts/observability/logs/log-drains/overview). All Aptible log drain integrations offer BAAs.

***

This document serves as a guide and does not replace professional legal advice. For detailed compliance questions, it is recommended to consult with legal experts or Aptible's support team.


# Image and Vulnerability Scanning
Source: https://www.aptible.com/docs/how-to-guides/platform-guides/image-vulnerability-scanning

Catch Docker image issues before deploy, and scan for new vulnerabilities between deployments

Maintaining image security doesn’t stop at deployment; it is a continuous process that must be implemented for every release by incorporating these steps in your CI/CD pipeline and image registry:

1. Lint Dockerfiles in CI before build
2. Scan built images in CI before deploy
3. Scan images on an ongoing basis between deployments

# Before Build: lint Dockerfiles in CI

Run Dockerfile linting in CI/CD on every change that touches your image definition. Linters help you catch common issues such as insecure defaults, unnecessary privileges, or outdated base image patterns before you spend time building or deploying.

Add linting as a required CI check so that a failing Dockerfile blocks the pipeline before the build step runs. This applies whether you [deploy via Git](/docs/how-to-guides/app-guides/deploy-from-git) or [deploy via Docker image](/docs/how-to-guides/app-guides/migrate-dockerfile-to-direct-image-deploy).

# Before Deploy: scan built images in CI

After the image is built, scan the artifact in your CI before deploying it. Open-source and commercial image scanners can inspect OS packages and other dependencies for known vulnerabilities. Fail the pipeline, or gate promotion, when findings exceed your policy standards.

Prefer [deploying via Docker image](/docs/how-to-guides/app-guides/migrate-dockerfile-to-direct-image-deploy) to ensure only the scanned artifact ships to production. Build once, scan the image, then deploy the same tagged image to staging and production.

When deploying via Git, Aptible builds the image at deploy time. Lint the Dockerfile in CI, and scan a deployed staging image before promoting the same commit to production. You cannot scan an image between when Aptible builds it and when it is deployed.

Wire scanning into your existing CI flow. See [How to deploy to Aptible with CI/CD](/docs/how-to-guides/app-guides/how-to-deploy-aptible-ci-cd) and [How to integrate Aptible with CI Platforms](/docs/how-to-guides/app-guides/integrate-aptible-with-ci/overview).

# Between deployments: ongoing and registry scanning

Vulnerabilities are disclosed after images are already running. Scanning only at deploy time leaves a gap until the next release. Cover that gap with one or both of:

* **Repository / registry scanning:** Many registries, like Docker Hub and Amazon ECR, can continuously or periodically scan stored images and alert when new CVEs appear against tags running in production.
* **Scheduled CI jobs:** Re-scan the image tags currently deployed to staging and production on a daily or weekly schedule. Treat new high-severity findings the same way you would in a pre-deploy gate: triage, rebuild, and redeploy when needed.

Ensure ongoing scans target the image digests or tags that are live in each environment, not only `latest`.

# Fitting this into Aptible deploys

| Phase           | Goal                                 | Git deploy                                                   | Image deploy                                      |
| --------------- | ------------------------------------ | ------------------------------------------------------------ | ------------------------------------------------- |
| Lint Dockerfile | Catch definition issues before build | Lint in CI before push                                       | Lint in CI before `docker build`                  |
| Scan image      | Catch known CVEs before production   | Scan staging image before promoting the commit to production | Scan the built image, then deploy that same image |
| Ongoing scan    | Catch new CVEs between deploys       | Registry or scheduled scans of deployed tags                 | Registry or scheduled scans of deployed tags      |

Image-based deploys make pre-deploy scanning straightforward because you control the build and can gate on the exact artifact. Git deploys still benefit from Dockerfile linting and from scanning staging before production.


# MedStack to Aptible Migration Guide
Source: https://www.aptible.com/docs/how-to-guides/platform-guides/medstack-migration

Learn how to migrate resources from MedStack to Aptible

# Overview

[Aptible](https://www.aptible.com/) is a PaaS (Platform as a Service) that provides developers with managed infrastructure and everything that they need to launch and scale apps that are secure, reliable, and compliant — with no need to manage infrastructure.

This guide will cover the differences between MedStack Control and Aptible and suggestions for how to migrate applications and resources.

# PaaS concepts

### Environment separation

In MedStack, environment separation is done using Clusters. In Aptible, data can be isolated using [Stacks](https://www.aptible.com/docs/core-concepts/architecture/stacks#stacks) and [Environments](https://www.aptible.com/docs/core-concepts/architecture/environments).

**Stacks**: A Stack in Aptible is most closely equivalent to a Cluster in MedStack. A Stack is an isolated network that contains the infrastructure required to run apps and databases on Aptible. A Shared Stack is a stack suitable for non-production workloads that do not contain PHI.

**Environments**: An Environment is a logical separation of resources. It can be used to group resources used in different stages of development (e.g., staging vs. prod) or to apply role-based permissions.

### Orchestration

In MedStack, orchestration is done via Docker Swarm. Aptible uses a built-in orchestration model that requires less management — you specify the size and number of containers to use for your application, and Aptible manages the allocation to underlying infrastructure nodes automatically. This means that you don’t have direct access to Nodes or resource pinning, but you don’t have to manage your resources in a way that requires access.

### Applications

In Aptible, you can **set up** applications via Git-based deploys where we build your Docker image based on your provided Dockerfile, or based on your pre-built Docker image, and define service name and command in a Procfile as needed. Configurations can be set in the UI or through the CLI.

To **deploy** the application, you can use `aptible deploy` or you can set up CI/CD for automated deployments from a repository.

To **scale** an application, you can use manual horizontal scaling (number of containers) and vertical scaling (size and profile of container). We also offer vertical and horizontal autoscaling, both available in beta.

### Databases and storage

MedStack is built on top of Azure. Aptible is built on top of AWS.

Our **managed database** offerings include support for PostgreSQL and MySQL, as well as other databases such as Redis, MongoDB, and [more](https://www.aptible.com/docs/core-concepts/managed-databases/overview). If you currently host any of the latter as database containers, you can host them as managed databases in Aptible.

Aptible doesn’t yet support **object storage**; for that, we recommend maintaining your storage in Azure and setting up connections from your hosted application in Aptible. For support for persistent volumes, please reach out to us.

### Downtime mitigation

Aptible’s [release process](https://www.aptible.com/docs/core-concepts/apps/deploying-apps/releases/overview#lifecycle) minimizes downtime while optimizing for container health. The platform runs [container health checks](https://www.aptible.com/docs/core-concepts/apps/connecting-to-apps/app-endpoints/https-endpoints/health-checks#health-check-lifecycle) during deployment and throughout the lifetime of the container.

### Metrics and logs

Aptible provides container [metrics](https://www.aptible.com/docs/core-concepts/observability/metrics/overview) and [logs](https://www.aptible.com/docs/core-concepts/observability/logs/overview) as part of the platform. You can view these within the Aptible UI, or you can set up [metrics](https://www.aptible.com/docs/core-concepts/observability/metrics/metrics-drains/overview) and [logs drains](https://www.aptible.com/docs/core-concepts/observability/logs/log-drains/overview) to your preferred destination.

# Compliance

**Compliance frameworks**: Aptible’s platform is designed to help businesses meet strict data privacy and security requirements. We offer built-in guardrails and infrastructure security controls that comply with the requirements of compliance frameworks such as HIPAA, HITRUST, PIPEDA, and [more](https://trust.aptible.com/). Compliance is built into how Aptible manages infrastructure, so no additional work is required to ensure that your application is compliant.

**Audit support**: We offer a [Security & Compliance dashboard](https://www.aptible.com/docs/core-concepts/security-compliance/security-compliance-dashboard/overview) that covers documentation and proof of infrastructure controls in the case of an audit.

**Security questionnaires**: In general, we don’t fill out security questionnaires on behalf of our customers. The Security & Compliance dashboard can be used as a resource to answer questionnaires. Our support team is available to answer specific one-off questions when needed.

# Pricing

MedStack’s pricing is primarily based on a platform fee with added pass-through infrastructure costs. Aptible’s pricing model differs slightly. Plan costs are mainly based on infrastructure usage, with a small platform fee for some plans.

Most companies will want to leverage our Production plan, which starts with a \$499/mo base fee and additional unit-based costs for resources.

For more details, see our [pricing page](https://www.aptible.com/pricing).

During the migration period, we will provide an extended free trial to allow you to leverage the necessary capabilities to try out and validate a migration of your services.

# Migrating a MedStack service to Aptible

This section walks through how to replicate and test your service on Aptible, prepare your database migration, and plan and execute a production migration plan.

### Create an Aptible account

* Create an Aptible account ([https://app.aptible.com/signup](https://app.aptible.com/signup)). Use a company email so that you automatically qualify for a free trial.
* Message Aptible support at [support@aptible.com](mailto:support@aptible.com) to let us know that you’re a MedStack customer and have created a trial account, and we will remove some customary resource limits from the free trial so that you can make a full deployment, validate for functionality, and estimate your pricing on Aptible.

### Replicate a MedStack staging service on Aptible

* [Create an Environment](https://www.aptible.com/docs/how-to-guides/platform-guides/create-environment#how-to-create-environments) in one of the available Stacks in your account
* Create required App(s): an Aptible App may contain one or more services that utilize the same Docker image
  * An App with multiple services can be defined using the [Procfile](https://www.aptible.com/docs/how-to-guides/app-guides/define-services#step-01-providing-a-procfile) standard
    * The Procfile file should be placed at **`/.aptible/Procfile`** in your pre-built Docker image
* Add any pre or post-release commands to [.aptible.yml](https://www.aptible.com/docs/core-concepts/apps/deploying-apps/releases/aptible-yml):
  * `before_release` is a common place to put commands like database migration tasks
  * .aptible.yml should be placed in **`/.aptible/.aptible.yml`** in your pre-built Docker image
* Set up config variables
  * Aptible makes use of environment variables to configure your apps. These settings can be modified via the [Aptible CLI](https://www.aptible.com/docs/reference/aptible-cli/cli-commands/cli-config-set) via `aptible config:set` or via the Configuration tab of your App in the web dashboard
* Add credentials for your Docker registry source
  * Docker credentials can be [provided via the command line](https://www.aptible.com/docs/core-concepts/apps/deploying-apps/image/deploying-with-docker-image/overview#private-registry-authentication) as arguments with the `aptible deploy` command
  * They can also be provided as secrets in your CI/CD workflow ([Github Actions Example](https://www.aptible.com/docs/how-to-guides/app-guides/how-to-deploy-aptible-ci-cd#deploying-with-docker))

### Deploy and validate your staging application

* Deploy your application using:
  * [`aptible deploy`](https://www.aptible.com/docs/reference/aptible-cli/cli-commands/cli-deploy#aptible-deploy) for Direct Docker Deployment using the Aptible CLI
  * Github Actions ([example](https://www.aptible.com/docs/how-to-guides/app-guides/how-to-deploy-aptible-ci-cd#deploying-with-docker))
  * Or, via git push if you are having us build your Docker Image by providing a Dockerfile in your git repo
* Add Endpoint(s)
  * An [Aptible Endpoint](https://www.aptible.com/docs/core-concepts/apps/connecting-to-apps/app-endpoints/overview) provides load balancer functionality for your App’s services.
  * We support a [“default domain” endpoint](https://www.aptible.com/docs/core-concepts/apps/connecting-to-apps/app-endpoints/default-domain) where you can have an [on-aptible.com](http://on-aptible.com) domain used for your test services without configuring a custom domain.
  * You can also configure [custom domain Endpoints](https://www.aptible.com/docs/core-concepts/apps/connecting-to-apps/app-endpoints/custom-domain#custom-domain), for which we can automatically provision certificates, or you can bring your own custom SSL certificates.
* Validate your App(s)

### Prepare your database migration

* Test the migration of your database to Aptible
  * This can be done via dump and restore methods:

    * PostgreSQL: using pg\_dump

    ```ruby theme={null}
    pg_dump -h [source_host] -p [source_port] -U [source_user] -W [source_database] > source_db_dump.sql

    psql -h [destination_host] -p [destination_port] -U [destination_user] -W [destination_database] < source_db_dump.sql
    ```

### Complete your Aptible setup

* Familiarize yourself with Aptible [activity](https://www.aptible.com/docs/core-concepts/observability/activity), [logs](https://www.aptible.com/docs/core-concepts/observability/logs/overview), [metrics](https://www.aptible.com/docs/core-concepts/observability/metrics/overview#metrics)
* (Optional) Set up [log](https://www.aptible.com/docs/core-concepts/observability/logs/log-drains/overview#log-drains) and [metric drains](https://www.aptible.com/docs/core-concepts/observability/metrics/metrics-drains/overview)
* Invite your team and [set up roles](https://www.aptible.com/docs/core-concepts/security-compliance/access-permissions)
* [Contact Aptible Support](https://contact.aptible.com/) to validate your production migration plan and set up a [Dedicated Stack](https://www.aptible.com/docs/core-concepts/architecture/stacks#dedicated-stacks-isolated) to host your production resources.

### Plan, Test and Execute the Migration

* Plan for the downtime required to migrate the database and perform DNS cutover for services behind load balancers to Aptible Endpoints. The total estimated downtime can be calculated by performing test database migrations and rehearsing manual migration steps.
* Key Points to consider in the Migration plan:
  * Be able to put app(s) in maintenance mode: before migrating databases for production systems, have a method available to ensure that no app services are connecting to the database for writes. Barring this, at least be able to scale app services to zero containers to take the app offline.
  * Consider modifying the DNS TTL on the records to be modified to value of 5 minutes or less.
  * Perform the database migration, and enable the Aptible app, potentially using a secondary [Default Domain Endpoint](https://www.aptible.com/docs/core-concepts/apps/connecting-to-apps/app-endpoints/default-domain) for testing, or using local /etc/hosts to override DNS temporarily.
  * Once the validation is complete, make the DNS record change to point your domain records to the new Aptible destination(s).
  * Monitor logs to ensure that requests transition fully to the Aptible Endpoint(s) (observe that requests cease at the MedStack Load Balancer, and appear in logs at the Aptible Endpoint).


# How to migrate environments
Source: https://www.aptible.com/docs/how-to-guides/platform-guides/migrate-environments

Learn how to migrate environments

## Migrating to a stack in the same region

It is possible to migrate environments from one [Stack](/docs/core-concepts/architecture/stacks) to another so long as both stacks are in the same [Region](/docs/core-concepts/architecture/stacks#supported-regions). The most common use case for this is migrating resources from a shared stack to a dedicated stack.

If you would like to migrate environments between stacks in the same region, please contact [Aptible Support](/docs/how-to-guides/troubleshooting/aptible-support) with details on the environment name and the stacks to and from which you want the environment migrated.

## Migrating to a stack in a different region

It is not possible to migrate environments from a stack in a different region, for example from a us-west-1  stack to a stack in us-west-2 . To achieve this, you must redeploy your resources to a new environment.


# Minimize Downtime Caused by AWS Outages
Source: https://www.aptible.com/docs/how-to-guides/platform-guides/minimize-downtown-outages

Learn how to optimize your Aptible resource to reduce the potential downtime caused by AWS Outages

## Overview

Aptible is designed to provide a baseline level of tools and services to minimize downtime from AWS outages. This includes:

* Automated configuration of [availability controls](https://www.aptible.com/secured-by-aptible/) designed to prevent outages

* Expert SRE response to outages backed by [our 99.95% Uptime SLA](https://www.aptible.com/legal/service-level-agreement/) (Enterprise Plan only)

* Simplification of additional downtime prevention measures (as described in the rest of this guide)

In this guide, we will cover into the various configurations and steps that can be implemented to enhance the Recovery Point Objective (RPO) and Recovery Time Objective (RTO). These improvements will assist in ensuring a more seamless and efficient recovery process in the event of any disruptions or disasters.

## Outage Notifications

If you think you are experiencing an outage, check Aptible's [Status Page](https://status.aptible.com/). We highly recommend subscribing to Aptible Status Page Notifications. If you still have questions, contact [Support](/docs/how-to-guides/troubleshooting/aptible-support).

> **Recommended Action:**

> 🎯 [Subscribe to Aptible Status Page Notifications](https://status.aptible.com/)

## Understanding AWS Infrastructure

Aptible runs on AWS so it helps to have a basic understanding of AWS's concept of [Regions and Availability Zones (AZs)](https://aws.amazon.com/about-aws/global-infrastructure/regions_az/).

## Regions

AWS regions are physical locations where AWS data centers are clustered. Communication between regions has a much higher-latency compared to communication within the same region and the farther two regions are from one another, the higher the latency. This means that it's generally better to deploy resources that work together within the same region.

Aptible Stacks are deployed in a single region in order to ensure resources can communicate with minimal latency.

## Availability Zones

AWS regions are comprised of multiple Availability Zones (AZs). AZs are sets of discrete data centers with redundant power, networking, and connectivity in a region. As mentioned above, communication within a region, and therefore between AZs in the same region, is very low latency. This allows resources to be distributed across AZs, increasing their availability, while still allowing them to communicate with minimal latency.

Aptible Stacks are distributed across 2 to 4 AZs depending on the region they're in. This enables all Stacks to distribute resources configured for high availability across AZs.

## High Availability

High Availability (HA) refers to distributing resources across data centers to increase the likelihood that one of the resources will be available at any given point in time.

As described above, Aptible Stacks will automatically distribute resources across the AZs in their region in order to maximize availability. Specifically, it does this by:

* Deploying the Containers for [Services scaled to multiple Containers](/docs/core-concepts/scaling/overview#horizontal-scaling) across AZs.

* Deploying [Database Replicas](/docs/core-concepts/managed-databases/managing-databases/replication-clustering) to a different AZ than the source Database is deployed to.

This alone enables you to be able to handle most outages and doesn't require a lot of effort which is why we recommend scaling production Services to at least 2 Containers and creating replicas for production Databases in the [Best Practices Guide](https://www.aptible.com/docs/best-practices-guide).

## Failover

Failover is the process of switching from one resource to another, generally in response to an outage or other incident that renders the resource unavailable. Some resources support automated failover whereas others require some manual intervention.

For Apps, Aptible [HTTP(S) Endpoints](/docs/core-concepts/apps/connecting-to-apps/app-endpoints/https-endpoints/overview) perform [Runtime Health Checks](/docs/core-concepts/apps/connecting-to-apps/app-endpoints/https-endpoints/health-checks#runtime-health-checks) to determine the status of App Containers and only send traffic to those that are considered "healthy". This means that all HTTP(S) Endpoints on Services scaled to 2 or more Containers will automatically be prepared for most minor outages.

Most Database types support manual failover in the form of promoting a replica and updating all of the Apps that used the original Database to use the promoted replica, instead. [MongoDB](/docs/core-concepts/managed-databases/supported-databases/mongodb) can dynamically failover between nodes in a cluster, similar to how HTTP(S) Endpoints only route traffic to "healthy" Containers, which enables them to handle minor outages without any action but can make multi-region failover more difficult. See the documentation for your [Database Type](/docs/core-concepts/managed-databases/supported-databases/overview) for details on setting up replication and failing over to a replica.

## Configuration and Planning

Organizations should decide how much downtime they can tolerate for their resources as the more fault-proof a solution is, the more it costs. We recommend planning for most common outages as Aptible makes it fairly easy to do so.

## Coverage for most outages

*Maturity Level: Standard*

The majority of AWS outages are limited hardware or networking failures affecting a small number of machines. Frequently this affects only a single [Availability Zone](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/using-regions-availability-zones.html), as AZs are isolated by design to share the minimum common causes of failures. Aptible's SRE team is notified in the event of AWS outages and responds to restore service based on what AWS resources are available. Most outages are able to be resolved in under 30 minutes by action of either AWS or Aptible without user action being required.

### Apps

The strongest basic step for making Apps resilient to most outages is [scaling each Service](https://www.aptible.com/docs/best-practices-guide#services) to 2 or more Containers. Aptible automatically schedules Containers to be run on hosts in different availability zones. In an outage affecting a single availability zone, traffic will be served only to Containers which are reachable and passing [health checks](/docs/core-concepts/apps/connecting-to-apps/app-endpoints/https-endpoints/health-checks#release-health-checks). Optimizing your App image to minimize tasks on container startup (such as installing or configuring software which could be built into the image instead) will allow Containers to be restarted more quickly to replace unhealthy or unreachable Containers and restore full capacity of the Service.

> **Recommended Action:**

> 🎯 [Scale Apps to 2+ Containers](https://app.aptible.com/controls/12/implementation)

### Databases

The simplest form of recovery that's available to all Database types is restoring one of the [Database's Backups](/docs/core-concepts/managed-databases/managing-databases/database-backups) to a new Database. However, Aptible automatically backups up Databases daily so the latest backup may be missing up to 24 hours of data so this approach is generally only recommended as a last resort.

[Replicas](/docs/core-concepts/managed-databases/managing-databases/replication-clustering), on the other hand, continuously stream data from their source Database so they're usually not more than a few seconds behind at any point in time. This means that replicas can be failed over to in the event that the source Database is unavailable for an extended period of time with minimal data loss. As mentioned in the [High Availability](/docs/how-to-guides/platform-guides/minimize-downtown-outages#high-availability) section, we recommend creating a replica for all production Databases that support replication. See the documentation for your [Database Type](/docs/core-concepts/managed-databases/supported-databases/overview) for details on setting up replication and failing over to a replica.

> **Recommended Action:**

> 🎯 [Implement Database Replication and Clustering](https://app.aptible.com/controls/14/implementation)

## Coverage for major outages

*Maturity Level: Advanced*

Major outages are much more rare and cost more to prepare for. See the [pricing page](https://www.aptible.com/pricing-plans/) for the current costs for each resource type. As such, organizations should evaluate the cost of preparing for an outage like this against the likelihood and impact it would have on their business before implementing these solutions.

To date, there's only been one AWS regional outage that would require this level of planning to be prepared for.

### Stacks

Since Stacks are deployed in a single region, an additional dedicated Stack is required in order to be able to handle region-wide outages. Contact [Aptible Support](/docs/how-to-guides/troubleshooting/aptible-support) if you'd like to provision an additional dedicated Stack.

When choosing what region to use as a backup, keep in mind that the further two regions are from each other the more latency there will be between them. Looking at the region that Aptible copies Backups to is a good starting point if you aren't sure.

You'll likely want to peer your two Stacks so that their resources can communicate with one another. In other words, this allows resources on one Stack can connect to Databases and Internal Endpoints on the other. This is also something that [Aptible Support](/docs/how-to-guides/troubleshooting/aptible-support) can set up for you.

> **Recommended Action:**

> 🎯 [Request a backup Dedicated Stack to be provisioned and/or peered](http://contact.aptible.com/)

### Apps

For a major outage, Apps will require manual intervention to failover to a different Stack in a healthy region. If you need a new Dedicated Stack provisioned as above, deploying your App to the new Stack will be equivalent to deploying it from scratch. If you maintain a Dedicated Stack in another region to be prepared in advance for a regional failure, there are several things you can do to speed the failover process.

You can deploy your production App's code to a second Aptible App on the backup Stack. Keeping the code and configuration in sync with your production Stack will allow you to failover to this App more quickly. To save costs, you can also scale all Services on this backup App to 0 Containers. In this case, failover will require [scaling each Service](/docs/core-concepts/scaling/overview) up from 0 before redirecting traffic to this App. Optimizing your App image to minimize startup time will speed up this process.

You will need to update DNS to point traffic toward Endpoints on the new App. Provisioning these Endpoints ahead of time will speed this process but will incur a small ongoing cost per Endpoint to have ready. Lowering DNS TTL will reduce failover time, and configuring these backup Endpoints with [custom certificates](/docs/core-concepts/apps/connecting-to-apps/app-endpoints/custom-certificate) is suggested to avoid the effort required to keep [Managed TLS](/docs/core-concepts/apps/connecting-to-apps/app-endpoints/managed-tls) certificates current on these Endpoints.

> **Recommended Action:**

> 🎯 [Deploy Apps to your backup Dedicated Stack](http://contact.aptible.com/)

> 🎯 [Provision Endpoints on your backup Dedicated Stack](/docs/core-concepts/managed-databases/connecting-databases/database-endpoints)

### Databases

The options for preparing for a major outage are the same as for other outages, restore a [Backup](/docs/core-concepts/managed-databases/managing-databases/database-backups) or failover to a [Replica](/docs/core-concepts/managed-databases/managing-databases/replication-clustering). The main difference here is that the resulting Database would be on a Stack in a different region and you'd have to continue operating on this Stack indefinitely or fail back over to the original Stack once it was back online.

Additionally, Aptible currently does not allow you to specify what Environment to create the Replica in with the [`aptible db:replicate` CLI command](/docs/reference/aptible-cli/cli-commands/cli-db-replicate) so Replicas are always created in the same Environment as the source Database. If you'd like to set up a Replica in another region, contact [Aptible Support](/docs/how-to-guides/troubleshooting/aptible-support) for assistance.

> **Recommended Action:**

> 🎯 [Enable Cross-Region Copy Database Backups](/docs/core-concepts/managed-databases/managing-databases/database-backups#retention-and-disposal)

> 🎯 [Request Replica(s) be moved to your backup Dedicated Stack](http://contact.aptible.com/)


# How to request HITRUST Inhertiance
Source: https://www.aptible.com/docs/how-to-guides/platform-guides/navigate-hitrust

Learn how to request HITRUST Inhertiance from Aptible

# Overview

Aptible makes achieving HITRUST a breeze with our Security & Compliance Dashboard and HITRUST Inhertiance.

<Tip>
  **What is HITRUST Inheritance?** Aptible is HITRUST CSF Certified. If you are pursuing your own HITRUST CSF Certification, you may request that Aptible assessment scores be incorporated into your own assessment. This process is referred to as HITRUST Inheritance.
</Tip>

While it varies per customer, approximately 30%-40% of controls can be fully inherited, and about 20%-30% of controls can be partially inherited.

## 01: Preparation

To comply with HITRUST, you must first:

* Provision a [Dedicated Stack](/docs/core-concepts/architecture/stacks) for all Environments that process PHI

* Sign a BAA with Aptible. BAAs can be requested by contacting [Aptible Support](/docs/how-to-guides/troubleshooting/aptible-support).

## 02: Requesting HITRUST Inheritance

<Info> HITRUST Inheritance is only available on the [Enterprise Plan](https://www.aptible.com/pricing). </Info>

The process for requesting [HITRUST Inheritance](/docs/core-concepts/security-compliance/overview#hitrust-inheritance) from Aptible is as follows:

* Navigate to [Aptible’s HITRUST Shared Responsibility Matrix](https://hitrustalliance.net/shared-responsibility-matrices) (SRM) to obtain a list of controls you can submit for HITRUST Inheritance. This document provides a list of all controls you can inherit from Aptible. To obtain the list of controls:

  * Read and agree to the general terms and conditions stated in the HITRUST Shared Responsibility Matrix License agreement.

  * Complete the form that appears, and you will receive an email within a few minutes after submission. Please check your spam folder if you don’t see the email after a few minutes.

  * Click the link to the HITRUST Shared Responsibility Matrix for Aptible in the email, and the list of controls will download to your computer.

* Using the list from the previous step, select which controls you would like to inherit and submit your request through MyCSF (Please note: Controls must be in “Submitted” status, not “Created”)

* [Contact Aptible Support](/docs/how-to-guides/troubleshooting/aptible-support) to let us know about your request in MyCSF. Note: This is the only way for us to communicate details to you about your request (including reasonings for rejections). Once you submit the inheritance request, our Support team will review and approve accordingly within MyCSF.

**Related resources:**

HITRUST’s Inheritance Program Fact
Navigating the MyCSF Portal (See 8.2.3 for more information on Submitting for Inheritance)


# How to navigate security questionnaires and audits
Source: https://www.aptible.com/docs/how-to-guides/platform-guides/navigate-security-questionnaire-audits

Learn how to approach responding to security questionnaires and audits on Aptible

## Overview

Aptible streamlines the process of addressing security questionnaires and audits with its pre-configured [Security & Compliance](/docs/core-concepts/security-compliance/overview) features. This guide will help you effectively showcase your security and compliance status for Aptible resources.

## 01: Define the scope

Before diving into the response process, it's crucial to clarify the scope of your assessment. Determine between controls within the scope of Aptible (e.g., infrastructure implementation) and those that fall outside of the scope (e.g., employee training on compliance policies).

For HITRUST Audits, Aptible provides the option of HITRUST Inheritance, which is a valuable resource for demonstrating compliance within the defined scope. Refer to [How to Request HITRUST Inheritance from Aptible.](/docs/how-to-guides/platform-guides/navigate-hitrust)

## 02: Gather resources

To ensure that you are well-prepared to answer questions and meet requirements, collect the most pertinent resources:

* For inquiries or requirements related to your unique setup (e.g., implementing Multi-Factor Authentication or redundancy configurations), refer to your Security & Compliance Dashboard. The [Security and Compliance Dashboard](/docs/core-concepts/security-compliance/security-compliance-dashboard/overview) provides an easy-to-consume view of all the HITRUST controls that are fully enforced and managed on your behalf. A printable report is available to share as needed.

* For inquiries or requirements regarding Aptible's compliance (e.g., HITRUST/SOC 2 reports) or infrastructure setup (e.g., penetration testing and host hardening), refer to our comprehensive [trust.aptible.com](http://trust.aptible.com/) page. This includes a FAQ of security questions.

## 03: Contact Support as needed

Should you encounter any obstacles or require further assistance during this process:

* If you are on the [Enterprise Plan](https://www.aptible.com/pricing), you have the option to request Aptible Support's assistance in completing an annual report when needed.

* Don't hesitate to reach out to [Aptible Support](/docs/how-to-guides/troubleshooting/aptible-support) for guidance.

## O4: Show off your compliance (optional)

Add a Secured by Aptible badge and link to the [Secured by Aptible](https://www.aptible.com/secured-by-aptible) page to show all the security & compliance controls implemented:

<img alt="" />

<img alt="" />

<img alt="" />

<img alt="" />

<img alt="" />


# Platform Guides
Source: https://www.aptible.com/docs/how-to-guides/platform-guides/overview

Explore guides for using the Aptible Platform

* [How to achieve HIPAA compliance on Aptible](/docs/how-to-guides/platform-guides/hipaa-compliance)

* [How to create and deprovison dedicated stacks](/docs/how-to-guides/platform-guides/create-deprovision-dedicated-stacks)

* [How to create environments](/docs/how-to-guides/platform-guides/create-environment)

* [How to delete environments](/docs/how-to-guides/platform-guides/delete-environment)

* [How to deprovision resources](/docs/how-to-guides/platform-guides/deprovision-resources)

* [How to migrate environments](/docs/how-to-guides/platform-guides/migrate-environments)

* [How to navigate security questionnaires and audits](/docs/how-to-guides/platform-guides/navigate-security-questionnaire-audits)

* [How to restore resources](/docs/how-to-guides/platform-guides/restore-resources)

* [How to upgrade or downgrade my plan](/docs/how-to-guides/platform-guides/upgrade-downgrade-plan)

* [How to set up Single Sign On (SSO)](/docs/how-to-guides/platform-guides/setup-sso)

* [Best Practices Guide](/docs/how-to-guides/platform-guides/best-practices-guide)

* [Advanced Best Practices Guide](/docs/how-to-guides/platform-guides/advanced-best-practices-guide)

* [Image and Vulnerability Scanning](/docs/how-to-guides/platform-guides/image-vulnerability-scanning)

* [How to navigate HITRUST Certification](/docs/how-to-guides/platform-guides/navigate-hitrust)

* [Minimize Downtime Caused by AWS Outages](/docs/how-to-guides/platform-guides/minimize-downtown-outages)

* [How to cancel my Aptible Account](/docs/how-to-guides/platform-guides/cancel-aptible-account)

* [How to reset my Aptible 2FA](/docs/how-to-guides/platform-guides/reset-aptible-2fa)


# How to Re-invite Deleted Users
Source: https://www.aptible.com/docs/how-to-guides/platform-guides/re-inviting-deleted-users



Users can be part of multiple organizations in Aptible. If you remove them from your specific organization, they will still exist in Aptible and can be members of other orgs.
This is why they will see “email is in use” when trying to create themselves as a new user.

Please re-send your invite to this user but instead of having them create a new user, have them log in using the link you sent. Please have them follow these steps exactly:

* Click on the link to accept the invite
* Instead of creating a new user, used the “sign in here” option
* If your organization uses SSO, please have them sign in with password authentication because SSO will not work for them until they are a part of the organization. If they have 2FA set up and don’t have access to their device, please have them follow the steps [here](https://www.aptible.com/docs/how-to-guides/platform-guides/reset-aptible-2fa).

Once these steps are completed, they should appear as a Member in the Members page in the Org Settings. If your organization uses SSO, please share the [SSO login link](https://www.aptible.com/docs/core-concepts/security-compliance/authentication/sso#organization-login-id) from with the new user and have them attempt to login via SSO.


# How to reset my Aptible 2FA
Source: https://www.aptible.com/docs/how-to-guides/platform-guides/reset-aptible-2fa



When you enable 2FA, you will receive emergency backup codes to use if your device is lost, stolen, or temporarily unavailable. Keep these in a safe place. You can enter backup codes where you would typically enter the 2FA code generated by your device. You can only use each backup code once.

If you don't have your device and cannot access a backup code, you can work with an account owner to reset your 2FA:

Account Owner:

1. Navigate to Settings > Members <img alt="" />

2. Select Reset 2FA for your user

3. Select Reset on the confirmation page <img alt="" />

User:

1. Click the link in the 2FA reset email you receive. <img alt="" />

2. Complete the reset on the confirmation page. <img alt="" />

3. Log in with your credentials.

4. Enable 2FA Authentication again in the Dashboard by navigating to Settings > Security Settings > Configure 2FA.

Account owners can reset 2FA for all other users, including other account owners, but cannot reset their own 2FA.


# How to Recover Deleted Resources
Source: https://www.aptible.com/docs/how-to-guides/platform-guides/restore-resources



## Apps

It is not possible to restore an App, its [Configuration](/docs/core-concepts/apps/deploying-apps/configuration), or its [Endpoints](/docs/core-concepts/apps/connecting-to-apps/app-endpoints/overview) once deprovisioned. Instead, deploy a new App using the same [Image](/docs/core-concepts/apps/deploying-apps/image/overview) and manually recreate the App's Configuration and any Endpoints.

## Database Backups

It is not possible to restore Database Backups once deleted. Aptible permanently deletes database backups when an account is closed. Users must export all essential data in Aptible before the account is closed.

## Databases

It is not possible to restore a Database, its [Endpoints](/docs/core-concepts/managed-databases/connecting-databases/database-endpoints) or its [Replicas](/docs/core-concepts/managed-databases/managing-databases/replication-clustering) once deprovisioned. Instead, create a new Database using the backed-up data from Database Backups via the [`aptible backup:restore`](/docs/reference/aptible-cli/cli-commands/cli-backup-restore) CLI command or through the Dashboard:

* Select the Backup Management tab within the desired environment.

* Select "Restore to a New Database" for the relevant backup.

Then, recreate any Database Endpoints and Replicas. Restoring a Backup creates a new Database from the backed-up data. It does not replace or modify the Database the Backup was originally created from in any way. The new Database will have the same data, username, and password as the original did at the time the Backup was taken.

## Log and Metric Drains

Once deleted, it is not possible to restore log and metric drains. Create new drains instead.

## Environments

Once deleted, it is not possible to restore Environments.


# Provisioning with Entra Identity (SCIM)
Source: https://www.aptible.com/docs/how-to-guides/platform-guides/scim-entra-guide

Aptible supports SCIM 2.0 provisioning through Entra Identity using the Aptible SCIM integration. This setup enables you to automate user provisioning and de-provisioning for your organization.

With SCIM enabled, users won't have the option to leave your organization on their own and won't be able to change their account email or password. Only organization owners have permission to remove team members. Entra Identity administrators can use SCIM to manage user account details if they're associated with a domain your organization verified.

> 📘 Note

> You must be an Aptible organization owner to enable SCIM for your organization.

### Step 1: Create a SCIM Integration in Aptible

1. **Log in to Aptible**: Sign in to your Aptible account with OrganizationOwner privileges.
2. **Navigate to Provisioning**: Go to the 'Settings' section in your Aptible dashboard and select Provisioning.

<img alt="" />

3. **Define Default Role**: Update the Default Aptible Role. New users created by SCIM will be automatically assigned to this role.
4. **Generate SCIM Token**: Aptible will provide a SCIM token, which you will need for Entra Identity configuration. Save this token securely; it will only be displayed once.

> 📘 Note

> Please note that the SCIM token has a validity of one year.

5. **Save the Changes**: Save the configuration.

### Step 2: Enable SCIM in Entra Identity

Entra Identity supports SCIM 2.0, allowing you to enable user provisioning directly through the Entra Identity portal.

1. **Access the Entra Identity Portal**: Log in to your Entra Identity admin center.
2. **Go to Enterprise Applications**: Navigate to Enterprise applications > All applications.
3. **Add an Application**: Click on 'New application', then select 'Non-gallery application'. Enter a name for your custom application (i.e., "Aptible") and add it.
4. **Setup SCIM**: In your custom application settings, go to the 'Provisioning' tab.
5. **Configure SCIM**: Click on 'Get started' and select 'Automatic' for the Provisioning Mode.
6. **Enter SCIM Connection Details**:
   * **Tenant URL**: Enter `https://auth.aptible.com/scim_v2`.
   * **Secret Token**: Paste the SCIM token you previously saved.
     <img alt="" />
7. **Test Connection**: Test the SCIM connection to verify that the SCIM endpoint is functional and that the token is correct.
8. **Save and Start Provisioning**: Save the settings and turn on provisioning to start syncing users.

### Step 3: Configure Attribute Mapping

Customize the attributes that Entra Identity will send to Aptible through SCIM:

1. **Adjust the Mapping**: In the 'Provisioning' tab of your application, select 'Provision Microsoft Entra ID Users' to modify the attribute mappings.

<img alt="" />

2. **Edit Attribute Mapping**: Ensure to align with what Aptible expects, focusing on core attributes like **User Principal Name**, **Given Name**, and **Surname**.

3. **Include required attributes**: Make sure to map essential attributes such as:
   * **userPrincipalName** to **userName**
   * **givenName** to **firstName**
   * **surname** to **familyName**
   * **Switch(\[IsSoftDeleted], , "False", "True", "True", "False")** to **active**
   * **mailNickname** to **externalId**

<img alt="" />

### Step 4: Test the SCIM Integration

1. **Test User Provisioning**: Create a test user in Entra Identity and verify that the user is provisioned in Aptible.
2. **Test User De-provisioning**: Deactivate or delete the test user in Entra Identity and confirm that the user is de-provisioned in Aptible.

By following these steps, you can successfully configure SCIM provisioning between Aptible and Entra Identity to automate your organization's user management.


# Provisioning with Okta (SCIM)
Source: https://www.aptible.com/docs/how-to-guides/platform-guides/scim-okta-guide

Aptible supports SCIM 2.0 provisioning through Okta using the Aptible SCIM integration. This setup enables you to automate user provisioning and de-provisioning for your organization.

With SCIM enabled, users won't have the option to leave your organization on their own, and won't be able to change their account email or password. Only organization owners have permission to remove team members. Only administrators in Okta have permission to use SCIM to change user account emails if they're associated with a domain your organization verified.

> 📘 Note

> You must be an Aptible organization owner to enable SCIM for your organization.

### Step 1: Create a SCIM Integration in Aptible

1. **Log in to Aptible**: Sign in to your Aptible account with OrganizationOwner privileges.
2. **Navigate to Provisioning**: Go to the 'Settings' section in your Aptible dashboard and select Provisioning

<img alt="" />

1. **Define Default Role**: Update the Default Aptible Role. New Users created by SCIM will be automatically assigned to this Role.
2. **Generate SCIM Token**: Aptible will provide a SCIM token, which you will need for the Okta configuration. Save this token securely; it will only be displayed once.

> 📘 Note

> Please note that the SCIM token has a validity of one year.

3. **Save the Changes**: Save the configuration.

### Step 2: **Enable SCIM in Okta with the SCIM test app**

The [SCIM 2.0 test app (Header Auth)](https://www.okta.com/integrations/scim-2-0-test-app-header-auth/) is available in the Okta Integration Network, allowing you to enable user provisioning directly through Okta.

Prior to enabling SCIM in Okta, you must configure SSO for your Aptible account

To set up provisioning with Okta, do the following:

1. Ensure you have the Aptible SCIM token generated in the previous step.
2. Open your Okta admin console in a new tab.
3. Go to **Applications**, and then select **Applications**.
4. Select **Browse App Catalog**.

<img alt="" />

5. Search for "SCIM 2.0 Test App (Header Auth)". Select the app from the results, and then select **Add Integration**.

<img alt="" />

6. In the **General Settings** tab, enter an app name you'll recognize later, and then select **Next**.
7. In the **Sign-On Options** tab, select **Done**.
8. In Okta, go to the newly created app, select **Provisioning**, then select **Configure API Integration**.

<img alt="" />

9. Select **Enable API integration**, and enter the following:
   * **Base URL** - Enter `https://auth.aptible.com/scim_v2`.
   * **API Token** - Enter your SCIM API key.

<img alt="" />

10. Select **Test API Credentials**. If successful, a verification message will appear.

    > If verification is unsuccessful, confirm that you have SCIM enabled for your team in Aptible, are using the correct SCIM API key, and that your API key's status is ACTIVE in your team authentication settings. If you continue to face issues, contact Aptible support for assistance.
11. Select **Save**. Then you can configure the SCIM 2.0 test app (Header Auth).

## Configure the SCIM test app

After you enable SCIM in Okta with the SCIM 2.0 test app (Header Auth), you can configure the app. The SCIM 2.0 test app (Header Auth) supports the provisioning features listed in the SCIM provisioning overview. The app also supports updating group information from Aptible to your IdP.

To turn these features on or off, do the following:

1. Go to the SCIM 2.0 test app (Header Auth) in Okta, select **Provisioning**, select **To App** on the left, then select **Edit**.

<img alt="" />

2. Select features to enable them or clear them to turn them off. Aptible supports the **Create users**, **Update User Attributes**, and **Deactivate Users** features. It doesn't support the **Sync Password** feature.

<img alt="" />

3. Select **Save** to save your changes.
4. Make sure only the **Username**, **Given name**, **Family name, and Display Name** attributes are mapped. Display Name is used if provided. Otherwise, the system will fall back to givenName and familyName. Other attributes are ignored if they're mapped.

<img alt="" />

5. Select **Assignments**, then assign relevant people and groups to the app. Learn how to [assign people and groups to an app in Okta](https://help.okta.com/en-us/content/topics/apps/apps-assign-applications.htm?cshid=ext_Apps_Apps_Page-assign).

<img alt="" />

## Step 3: Validate the SCIM Integration

1. **Validate User Provisioning**: Create a test user in Okta and verify that the user is provisioned in Aptible.
2. **Validate User De-provisioning**: Deactivate the test user in Okta and verify that the user is de-provisioned in Aptible.

By following these steps, you can successfully configure SCIM provisioning between Aptible and Okta to automate your organization's user management.


# How to set up Single Sign On (SSO)
Source: https://www.aptible.com/docs/how-to-guides/platform-guides/setup-sso

To use SSO, you must configure both the SSO provider and Aptible with metadata related to the SAML protocol. This documentation covers the process in general terms applicable to any SSO provider. Then, it covers in detail the setup process in Okta.

## Generic SSO Provider Configuration

To set up the SSO provider, it needs the following four pieces of information unique to Aptible. The values for each are available in your Organization's Single Sign On the settings page, accessible only by [Account Owners](/docs/core-concepts/security-compliance/access-permissions), if you do not yet have SSO configured.

<img alt="" />

You should reference your SSO Provider's walkthrough for setting up a SAML application alongside this documentation.

* [Okta](https://developer.okta.com/docs/guides/saml-application-setup/overview/)

* [Google GSuite](https://support.google.com/a/answer/6087519)

* [Auth0 (Aptible Guide)](/docs/how-to-guides/platform-guides/setup-sso-auth0)

## Single Sign On URL

The SAML protocol relies on a series of redirects to pass information back and forth between the SSO provider and Aptible. The SSO provider needs the Aptible URLs set ahead of time to securely complete this process. This URL is also called the Assertion Consumer Service (ACS) or SAML Consume URL by some providers.

Google uses the term `SSO URL` to refer to the redirect URL on their server. This value is called the `ACS URL` in their guide.

This is the first URL provided on the Aptible settings page. It should end in `saml/consume`.

## Audience URI

This is a unique identifier used by the SSO provider to match incoming login requests to your specific account with them. This may also be referred to as the Service Provider (SP) Entity ID.

Google uses the term `Entity ID` to refer to this value in its guide.

This is the second value on the Aptible information page. It should end in `saml/metadata`

> 📘 This URL provides all the metadata needed by an SSO provider to setup SAML for your account with Aptible. If your SSO provider, has an option to use this metadata, you can provide this URL to automate setup. Neither Okta nor Google allow for setup this way.

## Name ID Format

SAML requires a special "name" field that uniquely identifies the same user in both the SSO Provider and Aptible. Aptible requires that this field be the user's email address. That is how users are uniquely identified in our system.

There are several standard formats for this field. If your SSO supports the `EmailAddress`, `emailAddress`, or `Email` formats, one of which should be selected. If not, the `Unspecified` format, should be used. If none of those are available, `Persistent` format is also acceptable.

Some SSO providers do not require manual setting of the Name ID format and will automatically assign one based on the attribute selected in the next step.

## Application Attribute or Name ID Attribute

This tells the SSO provider want information to include as the required Name ID. The information it stores about your users is generally called attributes but may also be called fields or other names. This **must be set so that is the same email address as used on the Aptible account**. Most SSO providers have an email attribute that can be selected here. If not, you may have to create a custom attribute in your SSO provider.

You may optionally configure the SSO provider to send additional attributes, such as the user's full name. Aptible currently ignores any additional attributes sent.

> ❗️ Warning

> If the email address sent by the SSO provider does not exactly match the email address associated with their Aptible account, the user will not be able to login via your SSO provider. If users are having issues logging in, you should confirm those email addresses match.

## Other configuration fields

Your SSO provider may have many other configuration fields. You should be able to leave these at their default settings. We provide some general guidance if you do want to customize your settings. However, your SSO provider's documentation should supersede any information here as these values can vary from provider to provider.

* **Default RelayState or Start URL**: This allows you to set a default page on Aptible that your users will be taken to when logging in. We direct the user to the product they were using when they started logging in. You can override that behavior here if you want them to always start on a particular product.

* **Encryption, Signature, Digest Algorithms**: Prefer options with `SHA-256` over those with `SHA-1`.

## Aptible SSO Configuration

Once your have completed the SSO provider configuration, they should provide you with **XML Metadata** either as a URL or via file download.

Return to the Single Sign On settings page for your Organization, where you copied the values for setting up your SSO provider. Then click on the "Configure an SSO Provider"

<img alt="" />

In the resulting modal box, enter either the URL or the XML contents of the file. You only need to enter one. If you enter both, Aptible will use the URL to retrieve the metadata. Aptible will then complete our setup automatically.

> 📘 Note

> Aptible only supports SSO configurations with a single certificate at this time. If you get an error when applying your configuration, check to see if it contains multiple `KeyDescriptor` elements. If you require multiple certificates please notify [Aptible Support](/docs/how-to-guides/troubleshooting/aptible-support).

<img alt="" />

<Warning>
  Aptible requires HTTPS for metadata URLs. If you provide an HTTP URL, you'll receive an error: "metadata\_url invalid, ensure it uses https". HTTPS prevents tampering during download—without it, an attacker could substitute their own information and hijack your SSO configuration.
</Warning>

Once processing is complete, you should see data from your SSO provider. You can confirm these with the SSO provider's website to ensure they are correct.

You can optionally enable additional SSO feature within Aptible at this point:

## Okta Walkthrough

As a complement to the generic guide, we will present a detailed walkthrough for configuring Okta as an SSO provider to an Aptible Organization.

## Sign in to Okta with an admin account

* Click Applications in the main menu.

* Click Add Application and then Create New App.

## Setup a Web application with SAML 2.0

* The default platform should be Web. If not, select that option.

* Select SAML 2.0 as the Sign on method.

<img alt="" />

## Create SAML Integration

* Enter `Aptible Deploy` or another name of your choice.

* You may download and use our [logo](https://mintlify.s3-us-west-1.amazonaws.com/aptible/images/aptible_logo.png) for an image.

<img alt="" />

## Enter SAML Settings from Aptible Single Sign On Settings Page

* Open the Organization settings in Aptible Dashboard

* Select the Single Sign On settings in the sidebar

<img alt="" />

* Copy and paste the Single Sign On URL

* Copy and paste the Audience URI

* Select `EmailAddress` for the Name ID format dropdown

* Select `Email` in the Application username dropdown

* Leave all other values as their defaults

* Click Next

<img alt="" />

## Fill-in Okta's Feedback Page

* Okta will prompt you for feedback on the SAML setup.

* Select "I'm an Okta customer adding an internal app"

* Optionally, provide additional feedback.

* When complete, click Finish.

<img alt="" />

* Copy the link for Identity Provider metadata

<img alt="" />

* Open the Single Sign On settings page for your Organization in Aptible

* Click "Configure an SSO Provider"

* Paste the metadata URL into the box

<img alt="" />

## Assign Users to Aptible Deploy

* Follow [Okta's guide to assign users](https://developer.okta.com/docs/guides/saml-application-setup/assign-users-to-the-app/) to the new application.

## Troubleshooting Common SSO Configuration Errors

### Metadata URL Invalid Error

If you get "metadata\_url invalid, ensure it uses https", your metadata URL is using HTTP instead of HTTPS. Aptible requires HTTPS for all metadata URLs to prevent the metadata from being tampered with during retrieval.

Verify that your SSO provider's metadata URL begins with `https://`. Most modern SSO providers use HTTPS by default. If your provider only offers an HTTP metadata URL, use the metadata file XML content option instead.

### Metadata URL Timeout Error

If you get "metadata\_url request timed out", Aptible couldn't retrieve the metadata from your SSO provider within 5 seconds. This typically happens when the SSO provider's metadata endpoint is slow to respond, there are network connectivity issues between Aptible and your SSO provider, or the metadata endpoint is temporarily unavailable.

To fix this:

1. Wait a moment and try configuring the SSO provider again
2. Check with your SSO provider to ensure the metadata endpoint is accessible and responding quickly
3. Use the metadata file XML content option instead of the URL—download the metadata file from your SSO provider and paste its contents into the configuration form

<Tip>
  If you're experiencing repeated metadata URL issues, use the metadata file XML content option instead of the URL.
</Tip>

## Frequently Asked Questions

**What happens if my SSO provider suffers downtime?**

Users can continue to use their Aptible credentials to login even after SSO is enabled. If you also enabled [SSO enforcement](/docs/core-concepts/security-compliance/authentication/sso#require-sso-for-access) then your Account Owners can still login with their Aptible credentials and disable enforcement until the SSO provider is back online.

**Does Aptible offer automated provisioning of SSO users?**

Aptible supports SCIM 2.0 provisioning. Please refer to our [Provisioning Guide](/docs/core-concepts/security-compliance/authentication/scim).

**Does Aptible support Single Logout?**

We do not at this time. If this would be helpful for your Organization, please let us know.

**How can I learn more about SAML?**

There are many good references available on the Internet. We suggest the following starting points:

* [Understanding SAML](https://developer.okta.com/docs/concepts/saml/)

* [The Beer Drinker's Guide to SAML](https://duo.com/blog/the-beer-drinkers-guide-to-saml)

* [Overview of SAML](https://developers.onelogin.com/saml)

* [How SAML Authentication Works](https://auth0.com/blog/how-saml-authentication-works/)


# How to Set Up Single Sign-On (SSO) for Auth0
Source: https://www.aptible.com/docs/how-to-guides/platform-guides/setup-sso-auth0

This guide provides detailed instructions on how to set up a custom SAML application in Auth0 for integration with Aptible.

## Prerequisites

* An active Auth0 account
* Administrative access to the Auth0 dashboard
* Aptible Account Owner access to enable and configure SAML settings

## Creating Your Auth0 SAML Application

<Steps>
  <Step title="Accessing the Applications Dashboard">
    Log into your Auth0 dashboard. Navigate to **Applications** using the left navigation menu and click **Create Application**. Enter a name for your application (we suggest "Aptible"), select **Regular Web Applications**, and click **Create**.

    <img alt="" />
  </Step>

  <Step title="Enabling SAML2 WEB APP">
    Select the **Addons** tab and enable the **SAML2 WEB APP** add-on by toggling it on. Navigate to the **Usage** tab and download the Identity Provider Metadata or copy the link to it. Close this window—It will toggle back to off, which is expected. We will activate it later.

    <img alt="" />
  </Step>

  <Step title="Enable SAML Integration">
    Log into your Aptible dashboard as an Account Owner. Navigate to **Settings** and select **Single Sign-On**. Copy the following information; you will need it later:

    * **Single Sign-On URL** (Assertion Consumer Service \[ACS] URL):\
      `https://auth.aptible.com/organizations/xxxxx-xxx-xxxx-xxxx-xxxxxxxxxxxx/saml/consume`

      <img alt="" />
  </Step>

  <Step title="Upload Identity Provider Metadata">
    On the same screen, locate the option for **Metadata URL**. Copy the content of the metadata file you downloaded from Auth0 into **Metadata File XML Content**, or copy the link to the file into the **Metadata URL** field. Click **Save**. After the information has been successfully saved, copy the newly provided information:

    * **Shortcut SSO login URL**:\
      `https://app.aptible.com/sso/xxxxx-xxx-xxxx-xxxx-xxxxxxxxxxxx`

      <img alt="" />
  </Step>

  <Step title="Configuring SAML2 in Auth0">
    Return to the Auth0 SAML Application. In the Application under **Settings**, configure the following:

    * **Application Login URI**:\
      `https://app.aptible.com/sso/xxxxx-xxx-xxxx-xxxx-xxxxxxxxxxxx`
      (this is the Aptible value of **Shortcut SSO login URL**).
    * **Allowed Callback URLs**:\
      `https://auth.aptible.com/organizations/xxxxx-xxx-xxxx-xxxx-xxxxxxxxxxxx/saml/consume`
      (this is the Aptible value of **Single Sign-On URL - Assertion Consumer Service \[ACS] URL**).
    * Scroll down to **Advanced Settings -> Grant Types**. Select the grant type appropriate for your Auth0 configuration. Save the changes. Re-enable the **SAML2 WEB APP** add-on by toggling it on. Switch to the **Settings** tab. Copy the following into the **Settings** space (ensure that nothing else remains there):

    ```json theme={null}
    { 
      "nameIdentifierProbes": [ 
        "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress" 
      ] 
    }
    ```

    <img alt="" />
  </Step>

  <Step title="Finalize the Setup">
    Click on **Debug** — Ensure the opened page indicates "It works." Close this page, scroll down and select **Enable**.

    * Ensure that the correct users have access to your app (specific to your setup). Save the changes.

      <img alt="" />
  </Step>
</Steps>

### Attribute Mapping

No additional attribute mapping is required for the integration to function.

### Testing the Login

Open a new incognito browser window. Open the link Aptible provided as **Shortcut SSO login URL**. Ensure that you will be able to login.


# How to upgrade or downgrade my plan
Source: https://www.aptible.com/docs/how-to-guides/platform-guides/upgrade-downgrade-plan

Learn how to upgrade and downgrade your Aptible plan

## Overview

Aptible offers a number of plans to designed to meet the needs of companies at all stages. This guide will walk you through modifying your Aptible plan.

## Upgrading Plans

### Production

Follow these steps to upgrade your plan to Production plan:

* In the Aptible Dashboard, select your name at the top right

* Select Billing Settings in the dropdown that appears

* On the left, select Plan

* Choose the plan you would like to upgrade to

### Enterprise

For Enterprise or Custom plans, [please get in touch with us.](https://www.aptible.com/contact)

## Downgrading Plans

Follow these steps to downgrade your plan:

* In the Aptible dashboard, select your name at the top right

* Select Billing Settings in the dropdown that appears

* On the left, select Plan

* Choose the plan you would like to downgrade to

> ⚠️ Please note that your active resources must match the limits of the plan you select for the downgrade to succeed. For example: if you downgrade to a plan that only includes up to 3GB RAM - you must scale your resources below 3GB RAM before you can successfully downgrade.


# Aptible Support
Source: https://www.aptible.com/docs/how-to-guides/troubleshooting/aptible-support



<CardGroup>
  <Card title="Troubleshooting Guides" icon="magnifying-glass" href="https://www.aptible.com/docs/common-erorrs">
    Hitting an Error? Read our troubleshooting guides for common errors

    <br />

    View guides -->
  </Card>

  <Card title="Contact Support" icon="comment" href="https://contact.aptible.com/">
    Have a question? Reach out to Aptible Support

    <br />

    Contact Support -->
  </Card>
</CardGroup>

## **Best practices when opening a ticket**

* **Add Detail:** Please provide as much detail as possible to help us resolve your issue quickly. When appropriate, please include the following:

  * Relevant handles (App, Database, Environment, etc.)

  * Logs or error messages

  * The UTC timestamp when you experienced the issue

  * Any commands or configurations you have tried so far

* **Sanitize any sensitive information:** This includes [Database Credentials](/docs/core-concepts/managed-databases/connecting-databases/database-credentials), SSH keys, passwords, tokens, and any confidential [Configuration](/docs/core-concepts/apps/deploying-apps/configuration) variables you may use.

* **Format your support requests:** To make it easier to parse important information, use backticks for monospacing or triple backticks for code blocks. We suggest using [private GitHub Gists](https://gist.github.com/) for long code blocks or stack traces.

* **Set the appropriate priority:** This makes it easier for us to respond within the appropriate time frame.

## Ticket Priority

> 🏳️ High and Urgent Priority Support are only available on the [Premium & Enterprise Support plans.](https://www.aptible.com/pricing)

Users have the option to assign a priority level to their ticket submission, which is based on their [support plan](https://www.aptible.com/support-plans). The available priority levels include:

* **Low** (You have a general development question, or you want to request a feature)

* **Normal** (Non-critical functions of your application are behaving abnormally, or you have a time-sensitive development question)

* **High** (Important functions of your production application are impaired or degraded)

* **Urgent** (Your business is significantly impacted. Important functions your production application are unavailable)


# App Processing Requests Slowly
Source: https://www.aptible.com/docs/how-to-guides/troubleshooting/common-errors-issues/app-processing-requests-slowly



## Cause

If your app is processing requests slowly, it's possible that it is receiving more requests than it can efficiently handle at its current scale (due to hitting maxes with [CPU](/docs/core-concepts/scaling/cpu-isolation) or [Memory](/docs/core-concepts/scaling/memory-limits)).

## Resolution

First, consider deploying an [Application Performance Monitoring](/docs/how-to-guides/observability-guides/setup-application-performance-monitoring) solution in your App in order to get a better understanding of why it's running slow.

Then, if needed, see [Scaling](/docs/core-concepts/scaling/overview) for instructions on how to resize your App [Containers](/docs/core-concepts/architecture/containers/overview).


# Application is Currently Unavailable
Source: https://www.aptible.com/docs/how-to-guides/troubleshooting/common-errors-issues/application-unavailable



> 📘 If you have a [Custom Maintenance Page](/docs/core-concepts/apps/connecting-to-apps/app-endpoints/https-endpoints/maintenance-page#custom-maintenance-page) then you will see your maintenance page instead of *Application is currently unavailable*.

## Cause and Resolution

This page will be served by Aptible if your App fails to respond to a web request. There are several reasons why this might happen, each with different steps for resolution:

For further details about each specific occurrence, see [Endpoint Logs](/docs/core-concepts/apps/connecting-to-apps/app-endpoints/https-endpoints/endpoint-logs).

## The Service for your HTTP(S) Endpoint is scaled to zero

If there are no [Containers](/docs/core-concepts/architecture/containers/overview) running for the [Service](/docs/core-concepts/apps/deploying-apps/services) associated with your [HTTP(S) Endpoint](/docs/core-concepts/apps/connecting-to-apps/app-endpoints/https-endpoints/overview), this error page will be served. You will need to add at least one Container to your Service in order to serve requests.

## Your Containers are closing the connection without responding

Containers that have unexpectedly restarted will drop all requests that were running and will not respond to new requests until they have recovered. There are two reasons a Container would restart unexpectedly:

* Your Container exceeded the [Memory Limit](/docs/core-concepts/scaling/memory-limits) for your Service. You can tell if your Container has been restarted after exceeding its Memory Limit by looking for the message `container exceeded its memory allocation` in your [Logs](/docs/core-concepts/observability/logs/overview). If your Container exceeded its Memory Limit, consider [Scaling](/docs/core-concepts/scaling/overview) your Service.

* Your Container exited unexpectedly for some reason other than a deploy, restart, or exceeding its Memory Limit. This is typically caused by a bug in your App or one of its dependencies. If your Container unexpectedly exits, you will see `container has exited` in your logs. Your logs may also have additional information that can help you determine why your container unexpectedly exited.

## Your App is taking longer than the Endpoint Timeout to serve requests

Clients will be served this error page if your App takes longer than the [Endpoint Timeout](/docs/core-concepts/apps/connecting-to-apps/app-endpoints/overview#timeouts) to respond to their request. Your [Logs](/docs/core-concepts/observability/logs/overview) may contain request logs that can help you identify specific requests that are exceeding the Endpoint Timeout. If it's acceptable for some of your requests take longer than your current Endpoint Timeout to process, you can increase the Endpoint Timeout by configuring `--idle-timeout` on the endpoint (see [Endpoint Timeouts](/docs/core-concepts/apps/connecting-to-apps/app-endpoints/overview#timeouts)).

Hitting or exceeding resource limits may cause your App to respond to requests more slowly. Reviewing metrics from your Apps, either on the Aptible dashboard or from your [Metric Drains](/docs/core-concepts/observability/metrics/metrics-drains/overview), can help you identify if you are hitting any resource bottlenecks. If you find that you are hitting or exceeding any resource limits, consider [Scaling](/docs/core-concepts/scaling/overview) your App.

You should also consider deploying [Application Performance Monitoring](/docs/how-to-guides/observability-guides/setup-application-performance-monitoring) for additional insight into why your application is responding slowly.

If you see the Aptible error page that says "This application crashed" consistently every time you [release](/docs/core-concepts/apps/deploying-apps/releases/overview) your App (via Git push, `aptible deploy`, `aptible restart`, etc.), it's possible your App is responding to Aptible's [Release Health Checks](/docs/core-concepts/apps/connecting-to-apps/app-endpoints/https-endpoints/health-checks#release-health-checks), made via `GET /`, before the App is ready to serve other requests. Aptible's zero-downtime deployment process assumes that if your App responds to `GET /`, it is ready to respond successfully to other requests. If that assumption is not true, then your App cannot benefit from our zero-downtime approach, and you will see downtime accompanied by the Aptible error page after each release.

This situation can happen, for example, if your App runs a background process on startup, like precompiling static assets or loading a large data set, and blocks any requests (other than `GET /`) until this process is complete.

The best solution to this problem is to identify whatever background process is blocking requests and reconfigure your App to ensure this happens either (a) in your Dockerfile build or (b) in a startup script **before** your web server starts. Alternatively, you may consider enabling [Strict Health Checks](/docs/core-concepts/apps/connecting-to-apps/app-endpoints/https-endpoints/health-checks#strict-health-checks)] for your App, using a custom healthcheck request endpoint that only returns 200 when your App is actually ready to serve requests.

> 📘 Your [Endpoint Logs](/docs/core-concepts/apps/connecting-to-apps/app-endpoints/https-endpoints/endpoint-logs) will contain a specific error message for each of the above problems. You can identify the cause of each by referencing [Endpoint Common Errors](/docs/core-concepts/apps/connecting-to-apps/app-endpoints/https-endpoints/endpoint-logs#common-errors).


# App Logs Not Being Received
Source: https://www.aptible.com/docs/how-to-guides/troubleshooting/common-errors-issues/apps-logs-not-received



## Cause

There can be several causes why a [Log Drain](/docs/core-concepts/observability/logs/log-drains/overview) would stop receiving logs from your app:

* Your logging provider stopped accepting logs (e.g., because you are over quota)

* Your app stopped emitting logs

* The Log Drain crashed

## Resolution

You can start by restarting your Log Drain via the Dashboard. To do so, Navigate to the "Logging" Tab, then click on "Restart" next to the affected Log Drain.

If logs do not appear within a few minutes, the issue is likely somewhere else; contact [Aptible Support](/docs/how-to-guides/troubleshooting/aptible-support) for assistance.


# aptible ssh Operation Timed Out
Source: https://www.aptible.com/docs/how-to-guides/troubleshooting/common-errors-issues/aptible-ssh-operation-timed-out



When connecting using [`aptible ssh`](/docs/reference/aptible-cli/cli-commands/cli-ssh), you might encounter this error:

```
ssh: connect to host bastion-layer-$NAME.aptible.in port 1022: Operation timed out
```

## Cause

This issue is often caused by a firewall blocking traffic on port `1022` from your workstation to Aptible.

## Resolution

Try connecting from a different network or using a VPN (we suggest using [Cloak](https://www.getcloak.com/) if you need to quickly set up an ad-hoc VPN).

If that does not resolve your issue, contact [Aptible Support](/docs/how-to-guides/troubleshooting/aptible-support).


# aptible ssh Permission Denied
Source: https://www.aptible.com/docs/how-to-guides/troubleshooting/common-errors-issues/aptible-ssh-permission-denied



If you get an error indicating `Permission denied (publickey)` when using [`aptible ssh`](/docs/reference/aptible-cli/cli-commands/cli-ssh) (or [`aptible db:tunnel`](/docs/reference/aptible-cli/cli-commands/cli-db-tunnel), [`aptible logs`](/docs/reference/aptible-cli/cli-commands/cli-logs)), follow the instructions below.

This issue is caused by a bug in OpenSSH 7.8 that broke support for client certificates, which Aptible uses to authenticate [Ephemeral SSH Sessions](/docs/core-concepts/apps/connecting-to-apps/ssh-sessions) sessions.

This only happens if you installed the [Aptible CLI](/docs/reference/aptible-cli/cli-commands/overview) from source (as opposed to using the Aptible Toolbelt).

To fix the issue, follow the [Aptible CLI installation instructions](/docs/reference/aptible-cli/cli-commands/overview) and make sure to install the CLI using the Aptible Toolbelt package download.


# before_release Commands Failed
Source: https://www.aptible.com/docs/how-to-guides/troubleshooting/common-errors-issues/before-released-commands-fail



## Cause

If any of the [`before_release`](/docs/core-concepts/apps/deploying-apps/releases/aptible-yml#before-release) commands specified in your [`.aptible.yml`](/docs/core-concepts/apps/deploying-apps/releases/aptible-yml) fails i.e. exits with a non-zero status code, Aptible will abort your deployment.

If you are using `before_release` commands for e.g. database migrations, this is usually what you want.

## Resolution

When this happens, the deploy logs will include the output of your `before_release` commands so that you can start there for debugging.

Alternatively, it's often a good idea to try running your `before_release` commands via a [`aptible ssh`](/docs/reference/aptible-cli/cli-commands/cli-ssh) session in order to reproduce the issue.


# Build Failed Error
Source: https://www.aptible.com/docs/how-to-guides/troubleshooting/common-errors-issues/build-failed-error



## Cause

This error is returned when you attempt to [deploy via Git](/docs/how-to-guides/app-guides/deploy-from-git), but your [Dockerfile](/docs/core-concepts/apps/deploying-apps/image/deploying-with-git/overview) could not be built successfully.

## Resolution

The logs returned when you hit this error include the full output from the Docker build that failed for your Dockerfile. Review the logs first to try and identify the root cause.

Since Aptible uses [Docker](https://www.docker.com/), you can also attempt to reproduce the issue locally by [installing Docker locally](https://docs.docker.com/installation/) and then running `docker build .` from your app repository.

Once your app builds locally with a given Dockerfile, you can commit all changes to the Dockerfile and push the repo to Aptible, where it should also build successfully.


# Connecting to MongoDB fails
Source: https://www.aptible.com/docs/how-to-guides/troubleshooting/common-errors-issues/connecting-mongodb-fails



If you are connecting to a [MongoDB](/docs/core-concepts/managed-databases/supported-databases/mongodb) [Database](/docs/core-concepts/managed-databases/managing-databases/overview) on Aptible, either through your app or a [Database Tunnel](/docs/core-concepts/managed-databases/connecting-databases/database-tunnels), you might hit an error such as this one:

```sql theme={null}
MongoDB shell version: 3.2.1
connecting to: 172.17.0.2:27017/db
2016-02-08T10:43:40.421+0000 E QUERY    [thread1] Error: network error while attempting to run command 'isMaster' on host '172.17.0.2:27017'  :
connect@src/mongo/shell/mongo.js:226:14
@(connect):1:6

exception: connect failed
```

## Cause

This error is usually caused by attempting to connect without SSL to a MongoDB server that requires it, which is the case on Aptible.

## Resolution

To solve the issue, connect to your MongoDB server over SSL.

## Clients

Connection URLs generated by Aptible include the `ssl=true` parameter, which should instruct your MongoDB client to connect over SSL. If your client does not connect over SSL despite this parameter, consult its documentation.

## CLI

> 📘 Make sure you use a hostname to connect to MongoDB databases when using a database tunnel. If you use an IP address for the host, certificate verification will fail. You can work with `--sslAllowInvalidCertificates` in your command line, but using a hostname is simpler and safer.

The MongoDB CLI client does not accept database URLs. Use the following to connect:

```bash theme={null}
mongo --ssl \
        --username aptible --password "$PASSWORD" \
        --host "$HOST" --port "$PORT"
```


# Container Failed to Start Error
Source: https://www.aptible.com/docs/how-to-guides/troubleshooting/common-errors-issues/container-failed-start-error



## Cause and Resolution

If you receive an error such as `Failed to start containers for ...`, this is usually indicative of one of the following issues:

* The [Container Command](/docs/core-concepts/architecture/containers/overview#container-command) does not exist in your container. In this case, you should fix your `CMD` directive or [Procfile](/docs/how-to-guides/app-guides/define-services) to reference a command that does exist.

* Your [Image](/docs/core-concepts/apps/deploying-apps/image/overview) includes an `ENTRYPOINT`, but that `ENTRYPOINT` does not exist. In this case, you should fix your Image to use a valid `ENTRYPOINT`.

If neither is applicable to you, contact [Aptible Support](/docs/how-to-guides/troubleshooting/aptible-support) for assistance.


# Deploys Take Too long
Source: https://www.aptible.com/docs/how-to-guides/troubleshooting/common-errors-issues/deploys-take-long



When Aptible builds your App, it must run each of the commands in your Dockerfile. We leverage Docker's built-in caching support, which is described in detail in [Docker's documentation.](https://docs.docker.com/articles/dockerfile_best-practices/#build-cache)

> 📘 [Shared Stacks](/docs/core-concepts/architecture/stacks#shared-stacks) are more likely to miss the build cache than [Dedicated Stacks](/docs/core-concepts/architecture/stacks#dedicated-stacks)

To take full advantage of Docker's build caching, you should organize the instructions in your Dockerfile so that the most time-consuming build steps are more likely to be cached. For many apps, the dependency installation step is the most time-consuming, so you'll want to (a) separate that process from the rest of your Dockerfile instructions and (b) ensure that it happens early in the Dockerfile.

We provide specific instructions and Dockerfile snippets for some package managers in our [How to make Git deploys faster](/docs/how-to-guides/app-guides/make-docker-deploys-faster) tutorials.

You can also switch to [deploying via Docker image](/docs/how-to-guides/app-guides/migrate-dockerfile-to-direct-image-deploy) for full control over your build process.


# Enabling HTTP Response Streaming
Source: https://www.aptible.com/docs/how-to-guides/troubleshooting/common-errors-issues/enabling-http-response



## Problem

An Aptible user is attempting to stream HTTP responses from the server but notices that they are being buffered.

## Cause

By default, Aptible buffers requests at the proxy layer to protect against attacks that exploit slow uploads such as \[Slowloris]\(/docs/([https://en.wikipedia.org/wiki/Slowloris\_(computer\_security)](https://en.wikipedia.org/wiki/Slowloris_\(computer_security\))).

## Resolution

Aptible users can set the [`X-Accel-Buffering`](https://www.nginx.com/resources/wiki/start/topics/examples/x-accel/#x-accel-buffering) header to `no` to disable proxy buffering for these types of requests.

###### Enabling HTTP Response Streaming

* [Problem](/docs/how-to-guides/troubleshooting/common-errors-issues/enabling-http-response#problem)
* [Cause](/docs/how-to-guides/troubleshooting/common-errors-issues/enabling-http-response#cause)
* [Resolution](/docs/how-to-guides/troubleshooting/common-errors-issues/enabling-http-response#resolution)


# git Push "Everything up-to-date."
Source: https://www.aptible.com/docs/how-to-guides/troubleshooting/common-errors-issues/git-push-everything-utd



## Cause

This message means that the local branch you're pushing to Aptible is already at exactly the same revision as is currently deployed on Aptible.

## Resolution

* If you've already pushed your code to Aptible and simply want to restart the app, you can do so by running the [`aptible restart`](/docs/reference/aptible-cli/cli-commands/cli-restart) command. If you actually want to trigger a new build from the same code you've already pushed, you can use [`aptible rebuild`](/docs/reference/aptible-cli/cli-commands/cli-rebuild) instead.

* If you're pushing a branch other than `master`, you must still push to the remote branch named `master` in order to trigger a build. Assuming you've got a Git remote named `aptible`, you can do so with a command like the following `git push aptible local-branch:master`.


# git Push Permission Denied
Source: https://www.aptible.com/docs/how-to-guides/troubleshooting/common-errors-issues/git-push-permission-denied



When pushing to your [App](/docs/core-concepts/apps/overview)'s [Git Remote](/docs/how-to-guides/app-guides/deploy-from-git#git-remote), you may encounter a Permission denied error. Below are a few common reasons this may occur and steps to resolve them.

```sql theme={null}
Pushing to git@beta.aptible.com:[environment]/[app].git
Permission denied (publickey).
fatal: Could not read from remote repository.

Please make sure you have the correct access rights
and the repository exists.
```

## Wrong SSH Key

If you attempt to authenticate with a [public SSH key](/docs/core-concepts/security-compliance/authentication/ssh-keys) not registered with Aptible, Git Authentication will fail and raise this error.

To confirm whether Aptible’s Git server correctly authenticates you, use the ssh command below.

```
ssh -T git@beta.aptible.com test
```

On successful authentication, you'll see this message:

```
Hi [email]! Welcome to Aptible. Please use `git push` to connect.
```

On failure, you'll see this message instead:

```
git @beta.aptible.com: Permission denied(publickey).
```

## Resolution

The two most common causes for this error are that you haven't registered your [SSH Public Key](/docs/core-concepts/security-compliance/authentication/ssh-keys) with Aptible or are using the wrong key to authenticate.

From the SSH Keys page in your account settings (locate and click the Settings option on the bottom left of your Aptible Dashboard , then click the SSH Keys option), double-check you’ve registered an SSH key that matches the one you’re trying to use. If you’re still running into issues and have multiple public keys on your device, you may need to specify which key you want to use when connecting to Aptible. To do so, add the following to your local \~/.ssh/config file (you might need to create it):

```
Host beta.aptible.com
    IdentityFile /path/to/private/key
```

## Environment Permissions

If you don’t have the proper permissions for the Environment or because the Environment/App you’re pushing to doesn’t exist, you’ll also see the Permission denied (publickey) error above.

## Resolution

In the [Dashboard](https://app.aptible.com), check that you have the proper [permissions](/docs/core-concepts/security-compliance/access-permissions) for the Environment you’re pushing to and that the Git Remote you’re using matches the App’s Git Remote.


# git Reference Error
Source: https://www.aptible.com/docs/how-to-guides/troubleshooting/common-errors-issues/git-reference-error



You may encounter the following error messages when running a `git push` from a CI platform, such as Circle CI, Travis CI, Jenkins and others:

```bash theme={null}
error: Could not read COMMIT_HASH
fatal: revision walk setup failed
fatal: reference is not a tree: COMMIT_HASH
! [remote rejected] master -> master (missing necessary objects)
! [remote rejected] master -> master (shallow update not allowed)
```

(Where `COMMIT_HASH` is a long hexadecimal number)

## Cause

These errors are all caused by pushing from a [shallow clone](https://www.perforce.com/blog/141218/git-beyond-basics-using-shallow-clones).

Shallow clones are often used by CI platforms to make builds faster, but you can't push from a shallow clone to another git repository, which is why this fails when you try pushing to Aptible.

## Resolution

To solve this problem, update your build script to run this command before pushing to Aptible:

```bash theme={null}
git fetch --unshallow || true
```

If your CI platform uses an old version of git, `--unshallow` may not be available. In that case, you can try fetching a number of commits large enough to fetch all commits through to the repository root, thus unshallowing your repository:

```bash theme={null}
git fetch --depth=1000000
```


# HTTP Health Checks Failed
Source: https://www.aptible.com/docs/how-to-guides/troubleshooting/common-errors-issues/http-health-check-failed



## Cause

When your [App](/docs/core-concepts/apps/overview) has one or more [HTTP(S) Endpoints](/docs/core-concepts/apps/connecting-to-apps/app-endpoints/https-endpoints/overview), Aptible automatically performs [Health Checks](/docs/core-concepts/apps/connecting-to-apps/app-endpoints/https-endpoints/health-checks) during your deploy to make sure your [Containers](/docs/core-concepts/architecture/containers/overview) are properly responding to HTTP traffic.

If your containers are *not* responding to HTTP traffic, the health check fails.

These health checks are called [Release Health Checks](/docs/core-concepts/apps/connecting-to-apps/app-endpoints/https-endpoints/health-checks#release-health-checks).

## Resolution

There are several reasons why the health check might fail, each with its own fix:

If your app crashes immediately upon start-up, it's not healthy. In this case, Aptible will indicate that your Containers exited and report their [Container Command](/docs/core-concepts/architecture/containers/overview#container-command) and exit code.

You'll need to identify why your Containers are exiting immediately. There are usually two possible causes:

* There's a bug, and your container is crashing. If this is the case, it should be obvious from the logs. To proceed, fix the issue and try again.

* Your container is starting a program that immediately daemonizes. In this case, your container will appear to have exited from Aptible's perspective. To proceed, make sure the program you're starting stays in the foreground and does not daemonize, then try again.

## App listens on incorrect host

If your app is listening on `localhost` (a.k.a `127.0.0.1`), then Aptible cannot connect to it, so the health check won't pass.

Indeed, your app is running in Containers, so if the app is listening on `127.0.0.1`, then it's only routable from within those Containers, and notably, it's not routable from the Endpoint.

To solve this issue, you need to make sure your app is listening on all interfaces. Most application servers let you do so by binding to `0.0.0.0`.

## App listens on the incorrect port

If your Containers are listening on a given port, but the Endpoint is trying to connect to a different port, the health check can't pass.

There are two possible scenarios here:

* Your [Image](/docs/core-concepts/apps/deploying-apps/image/overview) does not expose the port your app is listening on.

* Your Image exposes multiple ports, but your Endpoint and your app are using different ports.

In either case, to solve this problem, you should make sure that:

* The port your app is listening on is exposed by your image. For example, if your app listens on port `8000`, your :ref:`Dockerfile` *must* include the following directive: `EXPOSE 8000`.

* Your Endpoint is using the same port as your app. By default, Aptible HTTP(S) Endpoints automatically select the lexicographically lowest port exposed by your image (e.g. if your image exposes port `443` and `80`, then the default is `443`), but you can select the port Aptible should use when creating the Endpoint and modify it at any time.

## App takes too long to come up

It's possible that your app Containers are is simply taking longer to finish booting up and start accepting traffic than Aptible is willing to wait.

Indeed, by default, Aptible waits for up to 3 minutes for your app to respond. However, you can increase that timeout by configuring `--release-healthcheck-timeout` on the endpoint (see [Release Health Check Timeout](/docs/core-concepts/apps/connecting-to-apps/app-endpoints/https-endpoints/health-checks#release-health-check-timeout)).

There is one particular error case worth mentioning here:

### Gunicorn and `[CRITICAL] WORKER TIMEOUT`

When starting a Python app using Gunicorn as your application server, the health check might fail with a repeated set of `[CRITICAL] WORKER TIMEOUT` errors.

These errors are generated by Gunicorn when your worker processes fail to boot within Gunicorn's timeout. When that happens, Gunicorn terminates the worker processes, then starts over.

By default, Gunicorn's timeout is 30 seconds. This means that if your app needs e.g., 35 seconds to boot, Gunicorn will repeatedly timeout and then restart it from scratch.

As a result, even though Aptible gives you 3 minutes to boot up (configurable via the `--release-healthcheck-timeout` endpoint setting), an app that needs 35 seconds to boot will time out on the Release Health Check because Gunicorn is repeatedly killing then restarting it.

Boot up may take longer than 30 seconds and hitting the timeout is common. Besides, you might have configured the timeout with a lower value (via the `--timeout` option).

There are two recommended strategies to address this problem:

* **If you are using a synchronous worker in Gunicorn (the default)**, use Gunicorn's `--preload` flag. This option will cause Gunicorn to load your app **before** starting worker processes. As a result, when the worker processes are started, they don't need to load your app, and they can immediately start listening for requests instead (which won't time out).

* **If you are using an asynchronous worker in Gunicorn**, increase your timeout using Gunicorn's `--timeout` flag.

> 📘 If neither of the options listed above satisfies you, you can also reduce your worker count using Gunicorn's `--workers` flag, or scale up your Container to make more resources available to them.

> We don't recommend these options to address boot-up timeouts because they affect your app beyond the boot-up stage, respectively by reducing the number of available workers and increasing your bill.

> That said, you should definitely consider making changes to your worker count or Container size if your app is performing poorly or [Metrics](/docs/core-concepts/observability/metrics/overview) are reporting you're undersized: just don't do it *only* for the sake of making the Release Health Check pass.

## App is not expecting HTTP traffic

[HTTP(S) Endpoints](/docs/core-concepts/apps/connecting-to-apps/app-endpoints/https-endpoints/overview) expect your app to be listening for HTTP traffic. If you need to expose an app that's not expecting HTTP traffic, you shouldn't be using an HTTP(S) Endpoint.

Instead, you should consider [TLS Endpoints](/docs/core-concepts/apps/connecting-to-apps/app-endpoints/tls-endpoints) and [TCP Endpoints](/docs/core-concepts/apps/connecting-to-apps/app-endpoints/tcp-endpoints).


# MySQL Access Denied
Source: https://www.aptible.com/docs/how-to-guides/troubleshooting/common-errors-issues/mysql-access-denied



## Cause

This error likely means that your [MySQL](/docs/core-concepts/managed-databases/supported-databases/mysql) client is trying to connect without SSL, but MySQL [Databases](/docs/core-concepts/managed-databases/managing-databases/overview) on Aptible require SSL.

## Resolution

Review our instructions for [Connecting to MySQL](/docs/core-concepts/managed-databases/supported-databases/mysql#connecting-to-mysql). Contact [Aptible Support](/docs/how-to-guides/troubleshooting/aptible-support) if you need further assistance.


# No CMD or Procfile in Image
Source: https://www.aptible.com/docs/how-to-guides/troubleshooting/common-errors-issues/no-cmd-procfile-image



### Cause

Aptible relies on your [Image's](/docs/core-concepts/apps/deploying-apps/image/overview) `CMD` or the presence of a [Procfile](/docs/how-to-guides/app-guides/define-services) in order to define [Services](/docs/core-concepts/apps/deploying-apps/services) for your [App](/docs/core-concepts/apps/overview).

If your App has neither, the deploy cannot succeed.

### Resolution

Add a `CMD` directive to your image, or add a Procfile in your repository.


# Operation Restricted to Availability Zone(s)
Source: https://www.aptible.com/docs/how-to-guides/troubleshooting/common-errors-issues/operation-restricted-to-availability



## Cause

Since there is varied support for container profiles per availability zone (AZ), [scaling](/docs/core-concepts/scaling/overview) a database to a different [container profile](/docs/core-concepts/scaling/container-profiles) may require moving the database to a different AZ. Moving a database to a different AZ requires a complete backup and restore of the underlying disk, which results in downtime of a few minutes up to even hours, depending on the size of the disk.

To protect your service from unexpected downtime, scaling to a container profile that requires an AZ move will result in an error and no change to your service. The error you see in logs will look something like:

```
ERROR -- : Operation restricted to availability zone(s) us-east-1e where m5 is not available. Disks cannot be moved to a different availability zone without a complete backup and restore.
```

## Resolution

If you still want to scale to a container profile that will result in an availability zone move, you can plan for the backup and restore by first looking at recent database backups and noting the time it took them to complete. You should expect roughly this amount of downtime for the **backup only**. You can speed up the backup portion of the move by creating a manual backup before running the operation since backups are incremental.

When restoring your database from a backup, you may initially experience slower performance. This slowdown occurs because each block on the restored volume is read for the first time from slower, long-term storage. This 'first-time' read is required for each block and affects different databases in various ways:

* For large PostgreSQL databases with busy access patterns and longer-than-default checkpoint periods, you may face delays of several minutes or more. This is due to the need to read WAL files before the database becomes online and starts accepting connections.

* Redis databases with persistence enabled could see delays in startup times as disk-based data must be read back into memory before the database is online and accepting connections.

* Databases executing disk-intensive queries will experience slower initial query performance as the data blocks are first read from the volume.

Depending on the amount of data your database needs to load into memory to start serving connections, this part of the downtime could be significant and might take more than an hour for larger databases. If you're running a large or busy database, we strongly recommend testing this operation on a non-production instance to estimate the total downtime involved.

When you're ready to move, go to the Aptible Dashboard, find your database, go to the settings panel, and select the container profile you wish to migrate to in the "Restart Database with Disk Backup and Restore" panel. After acknowledging the warning about downtime, click the button and your container profile scaling operation will begin.


# Common Errors and Issues
Source: https://www.aptible.com/docs/how-to-guides/troubleshooting/common-errors-issues/overview



Knowledge base for navigating common errors & issues:

* [App Logs Not Being Received](/docs/how-to-guides/troubleshooting/common-errors-issues/apps-logs-not-received)
* [App Processing Requests Slowly](/docs/how-to-guides/troubleshooting/common-errors-issues/app-processing-requests-slowly)
* [Application is Currently Unavailable](/docs/how-to-guides/troubleshooting/common-errors-issues/application-unavailable)
* [aptible ssh Operation Timed Out](/docs/how-to-guides/troubleshooting/common-errors-issues/aptible-ssh-operation-timed-out)
* [aptible ssh Permission Denied](/docs/how-to-guides/troubleshooting/common-errors-issues/aptible-ssh-permission-denied)
* [before\_release Commands Failed](/docs/how-to-guides/troubleshooting/common-errors-issues/before-released-commands-fail)
* [Build Failed Error](/docs/how-to-guides/troubleshooting/common-errors-issues/build-failed-error)
* [Connecting to MongoDB fails](/docs/how-to-guides/troubleshooting/common-errors-issues/connecting-mongodb-fails)
* [Container Failed to Start Error](/docs/how-to-guides/troubleshooting/common-errors-issues/container-failed-start-error)
* [Deploys Take Too long](/docs/how-to-guides/troubleshooting/common-errors-issues/deploys-take-long)
* [Enabling HTTP Response Streaming](/docs/how-to-guides/troubleshooting/common-errors-issues/enabling-http-response)
* [git Push "Everything up-to-date."](/docs/how-to-guides/troubleshooting/common-errors-issues/git-push-everything-utd)
* [git Push Permission Denied](/docs/how-to-guides/troubleshooting/common-errors-issues/git-push-permission-denied)
* [git Reference Error](/docs/how-to-guides/troubleshooting/common-errors-issues/git-reference-error)
* [HTTP Health Checks Failed](/docs/how-to-guides/troubleshooting/common-errors-issues/http-health-check-failed)
* [MySQL Access Denied](/docs/how-to-guides/troubleshooting/common-errors-issues/mysql-access-denied)
* [No CMD or Procfile in Image](/docs/how-to-guides/troubleshooting/common-errors-issues/no-cmd-procfile-image)
* [Operation Restricted to Availability Zone(s)](/docs/how-to-guides/troubleshooting/common-errors-issues/operation-restricted-to-availability)
* [PostgreSQL Incomplete Startup Packet](/docs/how-to-guides/troubleshooting/common-errors-issues/postgresql-incomplete)
* [PostgreSQL Replica max\_connections](/docs/how-to-guides/troubleshooting/common-errors-issues/postgresql-replica)
* [PostgreSQL SSL Off](/docs/how-to-guides/troubleshooting/common-errors-issues/postgresql-ssl-off)
* [Private Key Must Match Certificate](/docs/how-to-guides/troubleshooting/common-errors-issues/private-key-match-certificate)
* [SSL error ERR\_CERT\_AUTHORITY\_INVALID](/docs/how-to-guides/troubleshooting/common-errors-issues/ssl-error-auth-invalid)
* [SSL error ERR\_CERT\_COMMON\_NAME\_INVALID](/docs/how-to-guides/troubleshooting/common-errors-issues/ssl-error-common-name-invalid)
* [Unexpected Requests in App Logs](/docs/how-to-guides/troubleshooting/common-errors-issues/unexpected-requests-app-logs)


# PostgreSQL Incomplete Startup Packet
Source: https://www.aptible.com/docs/how-to-guides/troubleshooting/common-errors-issues/postgresql-incomplete



## Cause

When you add a [Database Endpoint](/docs/core-concepts/managed-databases/connecting-databases/database-endpoints) to a [PostgreSQL](/docs/core-concepts/managed-databases/supported-databases/postgresql) Database, Aptible automatically performs periodic TCP health checks to ensure the Endpoint can reach the Database.

These health checks consist of opening a TCP connection to the Database and closing it once that succeeds. As a result, PostgreSQL will log a `incomplete startup packet` error message every time the Endpoint performs a health check.

## Resolution

If you have a Database Endpoint associated with your PostgreSQL Database, you can safely ignore these messages. You might want to consider adding filtering rules in your logging provider to drop the messages entirely.


# PostgreSQL Replica max_connections
Source: https://www.aptible.com/docs/how-to-guides/troubleshooting/common-errors-issues/postgresql-replica



A PostgreSQL replica's `max_connections` setting must be greater than or equal to the primary's setting; if the value is increased on the primary before being changed on the replica it will result in the replica becoming inaccessible with the following error:

```
FATAL:  hot standby is not possible because max_connections = 1000 is a
lower setting than on the master server (its value was 2000)
```

Our SRE Team is alerted when a replica fails for this reason and will take action to correct the situation (generally by increasing `max_connections` on the replica and notifying the user).

To avoid this issue, you need to update `max_connections` on the replica Database to the higher value *before* updating the value on the primary.


# PostgreSQL SSL Off
Source: https://www.aptible.com/docs/how-to-guides/troubleshooting/common-errors-issues/postgresql-ssl-off



## Cause

This error means that your [PostgreSQL](/docs/core-concepts/managed-databases/supported-databases/postgresql) client is configured to connect to without SSL, but PostgreSQL [Databases](/docs/core-concepts/managed-databases/managing-databases/overview) on Aptible require SSL.

## Resolution

Many PostgreSQL clients allow enforcing SSL by appending `?ssl=true` to the default database connection URL provided by Aptible.

For some clients or libraries, it may be necessary to set this in the configuration code.

If you have questions about enabling SSL for your app's PostgreSQL library, please contact [Aptible Support](/docs/how-to-guides/troubleshooting/aptible-support).


# Private Key Must Match Certificate
Source: https://www.aptible.com/docs/how-to-guides/troubleshooting/common-errors-issues/private-key-match-certificate



## Cause

Your [Custom Certificate](/docs/core-concepts/apps/connecting-to-apps/app-endpoints/custom-certificate) is malformed or incomplete, or the private key you uploaded is not the right one for the certificate you uploaded.

## Resolution

Review the instructions here: [Custom Certificate Format](/docs/core-concepts/apps/connecting-to-apps/app-endpoints/custom-certificate#format).


# SSL error ERR_CERT_AUTHORITY_INVALID
Source: https://www.aptible.com/docs/how-to-guides/troubleshooting/common-errors-issues/ssl-error-auth-invalid



## Cause

This error is usually caused by neglecting to include CA intermediate certificates when you upload a [Custom Certificate](/docs/core-concepts/apps/connecting-to-apps/app-endpoints/custom-certificate) to Aptible.

## Resolution

Include CA intermediate certificate in your certificate bundle. See [Custom Certificate](/docs/core-concepts/apps/connecting-to-apps/app-endpoints/custom-certificate) for instructions.


# SSL error ERR_CERT_COMMON_NAME_INVALID
Source: https://www.aptible.com/docs/how-to-guides/troubleshooting/common-errors-issues/ssl-error-common-name-invalid



## Cause and Resolution

This error usually indicates one of two things:

* You created a CNAME to an [Endpoint](/docs/core-concepts/apps/connecting-to-apps/app-endpoints/overview) configured to use a [Default Domain](/docs/core-concepts/apps/connecting-to-apps/app-endpoints/default-domain). That won't work; use a [Custom Domain](/docs/core-concepts/apps/connecting-to-apps/app-endpoints/custom-domain) instead.

* The [Custom Certificate](/docs/core-concepts/apps/connecting-to-apps/app-endpoints/custom-certificate) you provided for your Endpoint is not valid for the [Custom Domain](/docs/core-concepts/apps/connecting-to-apps/app-endpoints/custom-domain) you're using. Get a valid certificate for the domain.


# Managing a Flood of Requests in Your App
Source: https://www.aptible.com/docs/how-to-guides/troubleshooting/common-errors-issues/unexpected-request-volume



When your app experiences a sudden flood of requests, it can degrade performance, increase latency, or even cause downtime. This situation is common for apps hosted on public endpoints with infrastructure scaled for low traffic, such as MVPs or apps in the early stages of product development.

This guide outlines steps to detect, analyze, and mitigate such floods of requests on the Aptible platform, along with strategies for long-term preparation.

## Detecting and Analyzing Traffic

Use **Endpoint Logs** to analyze incoming requests:

* **What to Look For**: Endpoint logs can help identify traffic spikes, frequently accessed endpoints, and originating networks.

* **Steps**:
  * Enable [Endpoint Logs](/docs/core-concepts/apps/connecting-to-apps/app-endpoints/https-endpoints/endpoint-logs) for your app.
  * Send logs to a third-party service (e.g., Papertrail, LogDNA, Datadog) using a [Log Drain](/docs/core-concepts/observability/logs/log-drains/overview). These services, depending on the features of each provider, allow you to:
    * Chart the volume of requests over time.
    * Analyze patterns such as bursts of requests targeting specific endpoints.

Use **APM Tools** to identify bottlenecks:

* **Purpose**: Application Performance Monitoring (APM) tools provide insight into performance bottlenecks.

* **Key Metrics**:
  * Endpoints with the highest request volumes.
  * Endpoints with the longest processing times.
  * Database queries or backend processes which represent bottlenecks with the increase in requests.

## Immediate Response

1. **Determine if Endpoint or resources should be public**:
   * If the app is not yet in production, consider implementing [IP Filtering](/docs/core-concepts/apps/connecting-to-apps/app-endpoints/ip-filtering) as a measure to only allow traffic from known IPs / networks.
   * Consider if all or portions of the app should be protected by authenticated means within your control.

2. **Investigate Traffic Source**:
   * **Authenticated Users**: If requests originate from authenticated users, verify the legitimacy and source.
   * **Public Activity**: Focus on high-traffic endpoints/pages and optimize their performance.

3. **Monitor App and Database Metrics**:
   * Use Aptible Metric Drains or viewing the in-app Aptible Metrics to observe CPU and memory usage of apps and databases during the event.

4. **Scale Resources Temporarily**:
   * Based on observations of metrics, scale app or database containers via the Aptible dashboard or CLI to handle increased traffic.
   * Specifically, if you see the `worker_connections are not enough` error message in your logs, horizontal scaling will help address this issue. See more about this error [here](/docs/core-concepts/apps/connecting-to-apps/app-endpoints/https-endpoints/endpoint-logs#worker-connections-are-not-enough).

5. **Validate Performance of Custom Error Pages**:
   * Ensure error pages (e.g., 404, 500) are lightweight and avoid backend processing or serving large or uncached assets.

## Long-Term Mitigation

1. **Authentication and Access Control**:
   * Protect sensitive resources or endpoints with authentication.

2. **Periodic Load Testing**:
   * Conduct load tests to identify and address bottlenecks.

3. **Horizontal Auto Scaling**:
   * Configure [horizontal auto scaling](/docs/how-to-guides/app-guides/horizontal-autoscaling-guide) for app containers.

4. **Optimize Performance**:
   * Use caching, database query optimization, and other performance optimization techniques to reduce processing time and load for high-traffic endpoints.

5. **Incident Response Plan**:
   * Document and rehearse a process for handling high-traffic events, including monitoring key metrics and scaling resources.

## Summary

A flood of requests doesn't have to bring your app down. By proactively monitoring traffic, optimizing performance, and having a well-rehearsed response plan, you can ensure that your app remains stable during unexpected surges.


# Unexpected Requests in App Logs
Source: https://www.aptible.com/docs/how-to-guides/troubleshooting/common-errors-issues/unexpected-requests-app-logs



When you expose an app to the Internet using [HTTP(S) Endpoints](/docs/core-concepts/apps/connecting-to-apps/app-endpoints/https-endpoints/overview) with [External Placement](/docs/core-concepts/apps/connecting-to-apps/app-endpoints/overview#endpoint-placement) will likely receive traffic from sources other than your intended users.

Some of this traffic may make requests for non-existent or non-sensical resources.

## Cause

This is normal on the Internet, and there are various reasons it might happen:

* An attacker is [fingerprinting you](http://security.stackexchange.com/questions/37839/strange-get-requests-to-my-apache-web-server)

* An attacker is [probing you for vulnerabilities](http://serverfault.com/questions/215074/strange-stuff-in-apache-log)

* A spammer is trying to get you to visit their site

* Someone is mistakenly sending traffic to you

## Resolution

This traffic is usually harmless as long as your app does not expose major unpatched vulnerabilities.

So, the best thing you can do is to take a proactive security posture that includes secure code development practices, regular security assessment of your apps, and regular patching.


# LLM Gateway
Source: https://www.aptible.com/docs/llm-gateway

Access 400+ models across Claude, GPT, Nova, Llama, Qwen, and more through a single, compliant API.

<Frame>
  <img alt="LLM Gateway Overview" />
</Frame>

## Overview

<Info>
  The LLM Gateway works as a standalone product or alongside your existing Aptible infrastructure. No apps or databases required. Sign up and start sending requests right away. See the [pricing page](https://www.aptible.com/pricing) for plan and usage details.
</Info>

Aptible's LLM Gateway gives you a single, compliant API for leading model providers, so your team can build securely with AI without having to configure directly with LLM providers. Through one endpoint and one key, you can:

* Access 400+ models across Claude, GPT, Nova, Llama, Qwen, and more through a single API
* Govern which models your team can use with environment-level model access policies
* Control and monitor spend with organization-wide limits, plus per-environment and per-key cost visibility
* Review request history and inspect full request and response logs to troubleshoot and refine prompts
* Drain traces to Langfuse for deeper observability
* Send PHI safely under Aptible's HIPAA BAA, with automatic audit logging and encryption

## Get Started

<Card title="Create your first LLM key" href="/getting-started/create-your-first-llm-key">
  Step-by-step guide covering key creation, initial setup, and the LLM Gateway's core features.
</Card>

## Supported Models

The LLM Gateway supports 400+ models across Claude, GPT, Nova, Llama, Qwen, and more. [See Supported Models for full details](/docs/supported-models).

<CardGroup>
  <Card title="Claude" icon="claude" href="/supported-models">
    `bedrock/anthropic` Haiku, Sonnet, and Opus
  </Card>

  <Card title="GPT & o-series" icon="openai" href="/supported-models">
    `openai` GPT-4o, GPT-4.1, GPT-5, o3, o4
  </Card>

  <Card title="Nova, Llama, Qwen & more" icon="sparkles" href="/supported-models">
    `bedrock` Amazon Nova, Meta Llama, Qwen & more
  </Card>
</CardGroup>

## Features

### Security & Compliance

The LLM Gateway is designed so compliance is built in at the infrastructure layer: not something your team has to configure or maintain. You route requests through the gateway; the controls apply automatically.

| Principle                         | How it works                                                                                                                                                                                        |
| --------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Centrally managed credentials** | Your raw provider API keys never leave Aptible. Developers and applications authenticate with scoped LLM keys. Rotate or revoke a key without touching any application code or provider settings.   |
| **Model access controls**         | Each environment has an allowlist of approved models. Any model not on the list is blocked for every key in that environment. Unapproved models are structurally unavailable, not just discouraged. |
| **Full audit trail**              | Every request and response is logged automatically — prompt content, response, model, key, token counts, cost, and timestamp. No configuration required.                                            |
| **No PHI model training**         | Providers accessed through the gateway are contractually prohibited from using your data for model training. This is enforced at the infrastructure layer, not by relying on provider-side policy.  |
| **HIPAA BAA coverage**            | Aptible's BAA covers all models and providers accessed through the gateway. You don't need separate BAAs per provider, and you don't need a dedicated stack to send PHI.                            |
| **Spend controls**                | A hard monthly spending cap prevents runaway costs from a misconfigured agent or a compromised key.                                                                                                 |

[Learn more about Security & Compliance →](/docs/llm-gateway/security-and-compliance-guardails)

### Model Access Policies

<Frame>
  <img alt="Screenshot 2026 06 03 At 3 48 23 PM" />
</Frame>

Control which models your team can use by configuring model access policies at the environment level. Policies apply to all LLM keys within an environment, giving you centralized control over model usage across your applications and developers.

[Learn more about Model Access Policies →](/docs/llm-gateway/model-access-policies)

### Cost Visibility & Control

<Frame>
  <img alt="Edit Monthly Spend Limit" />
</Frame>

Set an organization-wide monthly spending limit and track LLM usage at the organization, environment, and per-key level so you always know what's being spent and where.

[Learn more about Cost Visibility & Control →](/docs/llm-gateway/cost-control)

### Audit Logging

<Frame>
  <img alt="Logs Ui" />
</Frame>

Every LLM request and response is automatically logged. View request history and full request and response logs in the Aptible dashboard for 7 days, and drain traces to Langfuse for long-term retention and deeper observability.

[Learn more about Audit Logging →](/docs/llm-gateway/audit-logging)

## Support and Feedback

We'd love to hear from you as you use the LLM Gateway. If you have questions, run into issues, or have feature requests, [contact us](https://app.aptible.com/support).


# Audit Logging
Source: https://www.aptible.com/docs/llm-gateway/audit-logging

Review request history, inspect full request and response logs, and drain traces to Langfuse.

Aptible's LLM Gateway gives you full visibility into LLM activity. Every request is logged automatically with no configuration required.

<Info>
  If you're processing PHI: this feature satisfies the audit logging requirement under HIPAA's audit control standard. [See Security & Compliance for LLM Gateway for more info.](https://www.aptible.com/docs/llm-gateway/security-and-compliance-guardails)
</Info>

## What Gets Logged

Every request captures: prompt content, response, timestamp, model used, scope and key attribution, token counts (input and output), and cost. This gives you the full record needed to answer compliance questions, troubleshoot issues, and investigate incidents.

## Request History

View request activity for each key over the past week from the key details page. Each row shows token consumption and associated costs, giving you a quick read on how your keys are being used.

<Frame>
  <img alt="Screenshot 2026 06 03 At 4 28 38 PM" />
</Frame>

## Request Logs

Full LLM request and response logs are available in the Aptible dashboard for 7 days. Logs are useful for prompt refinement, troubleshooting, and compliance review. Click the chevron on any request row to expand the full request details.

<Frame>
  <img alt="Logs Ui" />
</Frame>

## Long-term Retention

For retention beyond 7 days, you can drain logs to Langfuse. LLM trace drains are configured at the environment level under the **Integrations** tab.

See the [Langfuse integration](/docs/core-concepts/integrations/langfuse) for setup instructions. If you have other retention requirements (S3, SIEM, etc.), [contact Aptible Support](https://app.aptible.com/support).

<Warning>
  Misconfigured log drains can fail silently. After setting up a drain, verify that logs are arriving in your destination before relying on it for compliance purposes. Contact [Aptible Support](https://app.aptible.com/support) if you want to set up alerting for drain delivery failures.
</Warning>


# Cost Visibility & Control for LLM Gateway
Source: https://www.aptible.com/docs/llm-gateway/cost-control

Set spending limits and track LLM usage across your organization, environments, and keys.

## Overview

Aptible's LLM Gateway gives you visibility into LLM spend at every level of your organization, from total usage across all environments down to individual key activity, and lets you set a hard cap to prevent unexpected costs.

## Setting a Spending Limit

You can set an organization-wide monthly spending limit to cap your total LLM Gateway usage. To configure it, click the gear icon in the monthly spend tile on the LLM Gateway Dashboard. The limit can be set anywhere between $1 and $10,000. If you need a higher limit, contact [Aptible Support](https://app.aptible.com/support).

<Frame>
  <img alt="Edit Monthly Spend Limit" />
</Frame>

## Tracking Spend

### Organization-level

See total LLM Gateway spend across all keys and environments for the current billing period from the main LLM Gateway Dashboard.

<Frame>
  <img alt="Screenshot 2026 06 03 At 4 16 11 PM" />
</Frame>

### Environment-level

View spend broken down by environment to understand which teams or applications are driving usage.

<Frame>
  <img alt="Screenshot 2026 06 03 At 4 18 26 PM" />
</Frame>

### Per-key

View usage costs for each individual LLM key during the current billing period to identify which keys generate the most activity and find opportunities for cost optimization.

<Frame>
  <img alt="Key Cost" />
</Frame>


# Langfuse Integration
Source: https://www.aptible.com/docs/llm-gateway/langfuse

Learn about using the Langfuse Integration for LLM observability and trace management

# Overview

Aptible integrates with [Langfuse](https://langfuse.com/), allowing you to send traces from the [Aptible LLM Gateway](/docs/llm-gateway) directly to your Langfuse project for LLM observability, debugging, and evaluation. You can send the following data directly to your Langfuse project:

* **LLM Traces:** Send request/response data, token usage, latency, and model metadata for every LLM Gateway call in an environment to your Langfuse project using an **LLM Trace Drain**.

<Info>LLM Trace Drains require your organization to sign a BAA and be enrolled in the [Aptible LLM Gateway beta](/docs/llm-gateway). If your organization isn't enrolled, the LLM Trace Drain option will not appear in the Aptible Dashboard.</Info>

<Warning>
  **LLM Trace Drains forward the full content of prompts and completions** to the configured Langfuse destination. If your LLM Gateway traffic includes PHI, PII, regulated data, or internal secrets, confirm that the Langfuse deployment you're sending to is HIPAA compliant and that you have a BAA with your provider before enabling a drain. Aptible's BAA covers the LLM Gateway itself; it does not extend to third-party destinations such as Langfuse Cloud.
</Warning>

## Langfuse LLM Trace Integration

On Aptible, you can set up a Langfuse LLM Trace Drain within an environment to forward every [LLM Gateway](/docs/llm-gateway) request originating from that environment to your Langfuse project. This enables you to use Langfuse's [tracing](https://langfuse.com/docs/tracing), [prompt management](https://langfuse.com/docs/prompts), and [evaluation](https://langfuse.com/docs/scores) features against real production LLM traffic running through the LLM Gateway.

### Prerequisites

Before creating a Langfuse LLM Trace Drain, you'll need:

* An environment enrolled in the LLM Gateway beta that has LLM keys in active use.
* A Langfuse project ([Langfuse Cloud](https://cloud.langfuse.com) or a self-hosted deployment) and its **Public Key**, **Secret Key**, and **Host URL** (e.g., `https://cloud.langfuse.com`).

<Info>
  **Hosting Langfuse on Aptible.** Aptible doesn't currently offer managed Langfuse hosting. Langfuse depends on [ClickHouse](https://clickhouse.com/) as its analytical backend, which isn't yet part of our [Managed Databases](/docs/core-concepts/managed-databases/supported-databases/overview) catalog. If Aptible-hosted Langfuse would be useful to you, [let us know](https://app.aptible.com/support) — customer demand shapes which database types we prioritize adding.
</Info>

<Accordion title="Creating a Langfuse LLM Trace Drain">
  A Langfuse LLM Trace Drain can be created within the Aptible Dashboard by:

  * Navigating to an Environment
  * Selecting the **Integrations** tab
  * Selecting **New LLM Trace Drain**
  * Selecting **Langfuse** as the type
  * Providing:
    * A **Handle** to identify the drain
    * The Langfuse **Base URL** (must use `https://`)
    * Your Langfuse project **Public Key** and **Secret Key**
  * Selecting **Save LLM Trace Drain**

  Once saved, all LLM Gateway requests made with API keys belonging to that environment are forwarded to the configured Langfuse project.
</Accordion>

<Info>
  **Interested in other destinations?** Langfuse is the first LLM Trace Drain destination Aptible supports. If you'd like to route LLM Gateway traces to another platform — or feed them into your existing OpenTelemetry-based observability stack — [reach out](https://app.aptible.com/support) and tell us what you're trying to do.
</Info>

### What Gets Sent

Each LLM Gateway request is forwarded to Langfuse as a single trace span. Traces follow the [CNCF OpenTelemetry GenAI semantic conventions](https://opentelemetry.io/docs/specs/semconv/gen-ai/gen-ai-spans/) (version 1.40.0) with additional Aptible-specific attributes. Every trace includes:

**Request and response content**

* Full input messages, system instructions, and tool definitions
* Full output messages (including tool calls) and finish reasons
* Request parameters: `model`, `max_tokens`, `temperature`, `top_p`, `top_k`, `frequency_penalty`, `presence_penalty`, `seed`, `stop_sequences`, `response_format`, and others

**Per-request metrics**

* Token counts — prompt, completion, total, and (where applicable) cache-creation and cache-read input tokens
* Cost and cost breakdown - Note that cost, spend, and budget values currently reflect list pricing from upstream providers and will vary as the LLM Gateway's pricing model evolves and based on customer contracts.
* Latency — total response time, time-to-first-token (completion start time), and gateway overhead
* Cache hit indicator, cache key, and cost savings on cache hits
* Provider rate-limit headers — request and token allowances and remaining budget

**Aptible identity and attribution**

* The originating Aptible organization ID, environment ID, API key hash, and key alias
* The resolved model ID and model group
* The API route, request ID, caller IP address, and user-agent
* Cumulative key spend, per-key budget, and budget reset time

**Error information**

* On failed requests, the error class and any error detail captured by the gateway

See [Langfuse's tracing documentation](https://langfuse.com/docs/tracing) for details on how traces are structured, searched, and visualized.

<Note>
  Traces arriving in Langfuse reflect the gateway's view of each request — the model that was actually invoked, the provider latency observed at the gateway, and the token counts Aptible is billing on. If your application also emits its own Langfuse traces, you can correlate gateway traces with application traces using the `x-session-id` request header (forwarded as `gen_ai.conversation.id`) or the `end_user` field.
</Note>


# LLM Keys
Source: https://www.aptible.com/docs/llm-gateway/llm-keys

How to create, manage, and revoke LLM Keys for the LLM Gateway.

## Overview

LLM Keys are API keys that authenticate requests to the Aptible AI Gateway. Each key is scoped to an environment, so you can organize usage across applications, teams, and deployment stages and apply model access policies and cost controls at that level.

A single key gives you access to all models available in that environment. You don't need separate keys per provider. See [Model Access Policies](/docs/llm-gateway/model-access-policies) for more info.

## Creating a Key

Go to the [AI Gateway Dashboard](https://app.aptible.com/llm-keys) and select **Create LLM Key**.

If you're getting set up for the first time, see the [Create your first LLM key](/docs/getting-started/create-your-first-llm-key) guide for a full walkthrough.

## Managing Keys

Keys are managed from the [AI Gateway Dashboard](https://app.aptible.com/llm-keys) in the Aptible dashboard. From the key list you can see each key's name, environment, current period spend, and last used date.

Click into any key to view its details, including request history for the past 7 days, token usage, and per-request costs.

## Revoking a Key

Keys can be revoked from the [AI Gateway Dashboard](https://app.aptible.com/llm-keys). Revoking a key immediately invalidates it. Use this if a key is compromised or you need to permanently cut off access for a specific application or team.


# Model Access Policies for LLM Gateway
Source: https://www.aptible.com/docs/llm-gateway/model-access-policies

Control which models your team can use at the environment level.

## Overview

Model Access Policies let you control which models are available for use with LLM Keys. Policies are configured at the environment level and apply to all keys within that environment.

## Environment-Level Policies

Environment-level policies set a global allowlist of models for all LLM keys within that environment. Any model not on the list is blocked for every key in that environment. This gives you centralized control over model usage across your applications and developers.

<Frame>
  <img alt="Screenshot 2026 06 03 At 3 48 23 PM" />
</Frame>

To configure a model access policy:

1. Navigate to your Environment in the Aptible dashboard
2. Click the **LLM Gateway** tab
3. Click **Edit policy** and select the models you want to allow

<Info>
  Model availability is subject to change. Check the LLM Key Details in the [LLM Gateway Dashboard](https://app.aptible.com/llm-keys) for the current list of available models.
</Info>


# Security & Compliance for LLM Gateway
Source: https://www.aptible.com/docs/llm-gateway/security-and-compliance-guardails

Security and compliance control enforced at the infrastructure layer for every LLM request.

## Overview

The LLM Gateway is designed for security-conscious teams and teams building with sensitive data. Compliance controls are enforced at the infrastructure layer, not in application code, so your team can ship AI features without building a custom compliance stack.

<Tip>
  If you're building a full application, consider Aptible's core platform for secure app and database hosting. Security and compliance guardrails are baked in and fully managed, so you can run your entire stack in a HIPAA-compliant environment without configuring it yourself. [Learn more about the Aptible platform](/docs/core-concepts).
</Tip>

### Compliance Controls Summary

| Control                | Aptible LLM Gateway                              |
| ---------------------- | ------------------------------------------------ |
| BAA coverage           | One BAA covers all models and providers          |
| Audit logging          | Automatic. Every request and response is logged. |
| Log retention & export | Log drain support for long-term storage          |
| Encryption             | Enforced in transit and at rest                  |
| No PHI model training  | Enforced at infrastructure layer                 |
| Key management         | Scoped to environments and applications          |
| Model access controls  | Restrict models per environment                  |

## HIPAA & BAA Coverage

Aptible's BAA covers all models and capabilities accessed through the LLM Gateway. A provider BAA from OpenAI or Anthropic covers the provider's liability, but it doesn't give you audit logging, access controls, or de-identification. Those are still your responsibility unless you route through a managed layer like Aptible.

To get a BAA with Aptible, [contact Aptible Support](https://app.aptible.com/support).

<Info>
  Unlike Aptible's core platform (app and database hosting), which requires a dedicated stack for HIPAA workloads, LLM Keys in a shared stack environment are also covered under the BAA. You don't need a dedicated stack to send PHI through the LLM Gateway.
</Info>

## Audit Logging

Every LLM request and response is automatically logged with no configuration required. Logs include full request and response payloads, token usage, model, cost, and timestamp. Logs are available in the Aptible dashboard for 7 days and can be drained to external systems for long-term retention.

This gives you the visibility needed to answer security questionnaires, support incident investigations, and demonstrate PHI handling during audits.

See [Audit Logging](/docs/llm-gateway/audit-logging) for details on viewing logs and configuring log drains.

## Encryption

All data is encrypted in transit (TLS) and at rest. This applies to all LLM requests, responses, and stored logs.

## No PHI Training

LLM providers accessed through the LLM Gateway are contractually prohibited from retaining or using your data, including PHI, for model training. This is enforced at the infrastructure layer, not just by relying on provider policy.

## Key Management & Access Controls

API keys are scoped to environments, giving you control over which applications and teams can call which models. Model access policies let you restrict which models are available within each environment, so you can prevent unauthorized use of specific providers or model versions.

See [Model Access Policies](/docs/llm-gateway/model-access-policies) for details.


# Supported Models for LLM Gateway
Source: https://www.aptible.com/docs/llm-gateway/supported-models

400+ supported model IDs across Claude, GPT, Nova, Llama, Qwen, and more.

## Overview

Aptible supports 400+ model IDs across the most widely used model families: Claude, GPT, Nova, Llama, Qwen, and many more. Models are accessed through OpenAI or Amazon Bedrock. You can configure and manage which models are available to your organization — see [Managing Model Access](#) for details.

<Info>
  Model availability is subject to change. Check the LLM Key Details in the [AI Gateway Dashboard](https://app.aptible.com/llm-keys) for the current list of available models.
</Info>

## Claude

Anthropic's Claude models are available via Amazon Bedrock, including regional inference profile variants with `us.`, `eu.`, `apac.`, `au.`, `jp.`, `global.`, and `us-gov.` prefixes.

* Legacy: `bedrock/anthropic.claude-instant-v1`, `bedrock/anthropic.claude-v1`, `bedrock/anthropic.claude-v2`, `bedrock/anthropic.claude-v2:1`
* Claude 3: `bedrock/anthropic.claude-3-haiku-20240307-v1:0`, `bedrock/anthropic.claude-3-sonnet-20240229-v1:0`, `bedrock/anthropic.claude-3-opus-20240229-v1:0`
* Claude 3.5: `bedrock/anthropic.claude-3-5-haiku-20241022-v1:0`, `bedrock/anthropic.claude-3-5-sonnet-20240620-v1:0`, `bedrock/anthropic.claude-3-5-sonnet-20241022-v2:0`
* Claude 3.7: `bedrock/anthropic.claude-3-7-sonnet-20240620-v1:0`, `bedrock/anthropic.claude-3-7-sonnet-20250219-v1:0`
* Claude Haiku 4.5: `bedrock/anthropic.claude-haiku-4-5-20251001-v1:0`, `bedrock/anthropic.claude-haiku-4-5@20251001`
* Claude Sonnet 4: `bedrock/anthropic.claude-sonnet-4-20250514-v1:0`
* Claude Sonnet 4.5: `bedrock/anthropic.claude-sonnet-4-5-20250929-v1:0`, `bedrock/claude-sonnet-4-5-20250929-v1:0`
* Claude Sonnet 4.6: `bedrock/anthropic.claude-sonnet-4-6`
* Claude Opus 4: `bedrock/anthropic.claude-opus-4-20250514-v1:0`
* Claude Opus 4.1: `bedrock/anthropic.claude-opus-4-1-20250805-v1:0`
* Claude Opus 4.5: `bedrock/anthropic.claude-opus-4-5-20251101-v1:0`
* Claude Opus 4.6: `bedrock/anthropic.claude-opus-4-6-v1`, `bedrock/anthropic.claude-opus-4-6-v1:0`
* Claude Opus 4.7: `bedrock/anthropic.claude-opus-4-7`
* Claude Opus 4.8: `bedrock/anthropic.claude-opus-4-8`

## GPT

OpenAI's GPT models are available via the OpenAI provider.

* GPT-3.5: `openai/gpt-3.5-turbo`, `openai/gpt-3.5-turbo-0125`, `openai/gpt-3.5-turbo-1106`, `openai/gpt-3.5-turbo-16k`, `openai/gpt-3.5-turbo-instruct`, `openai/gpt-3.5-turbo-instruct-0914`
* GPT-4: `openai/gpt-4`, `openai/gpt-4-0314`, `openai/gpt-4-0613`, `openai/gpt-4-1106-preview`, `openai/gpt-4-0125-preview`, `openai/gpt-4-turbo`, `openai/gpt-4-turbo-2024-04-09`, `openai/gpt-4-turbo-preview`
* GPT-4o: `openai/gpt-4o`, `openai/gpt-4o-2024-05-13`, `openai/gpt-4o-2024-08-06`, `openai/gpt-4o-2024-11-20`, `openai/gpt-4o-mini`, `openai/gpt-4o-mini-2024-07-18`, `openai/chatgpt-4o-latest`
* GPT-4.1: `openai/gpt-4.1`, `openai/gpt-4.1-2025-04-14`, `openai/gpt-4.1-mini`, `openai/gpt-4.1-mini-2025-04-14`, `openai/gpt-4.1-nano`, `openai/gpt-4.1-nano-2025-04-14`
* GPT-5: `openai/gpt-5`, `openai/gpt-5-2025-08-07`, `openai/gpt-5-chat`, `openai/gpt-5-chat-latest`, `openai/gpt-5-codex`, `openai/gpt-5-mini`, `openai/gpt-5-mini-2025-08-07`, `openai/gpt-5-nano`, `openai/gpt-5-nano-2025-08-07`, `openai/gpt-5-pro`, `openai/gpt-5-pro-2025-10-06`, `openai/gpt-5-search-api`, `openai/gpt-5-search-api-2025-10-14`, `openai/gpt-5.1`, `openai/gpt-5.1-2025-11-13`, `openai/gpt-5.1-chat-latest`, `openai/gpt-5.1-codex`, `openai/gpt-5.1-codex-max`, `openai/gpt-5.1-codex-mini`, `openai/gpt-5.2`, `openai/gpt-5.2-2025-12-11`, `openai/gpt-5.2-chat-latest`, `openai/gpt-5.2-codex`, `openai/gpt-5.2-pro`, `openai/gpt-5.2-pro-2025-12-11`, `openai/gpt-5.3-chat-latest`, `openai/gpt-5.3-codex`, `openai/gpt-5.4`, `openai/gpt-5.4-2026-03-05`, `openai/gpt-5.4-mini`, `openai/gpt-5.4-mini-2026-03-17`, `openai/gpt-5.4-nano`, `openai/gpt-5.4-nano-2026-03-17`, `openai/gpt-5.4-pro`, `openai/gpt-5.4-pro-2026-03-05`, `openai/gpt-5.5`, `openai/gpt-5.5-2026-04-23`, `openai/gpt-5.5-pro`, `openai/gpt-5.5-pro-2026-04-23`
* Reasoning (o-series): `openai/o1`, `openai/o1-2024-12-17`, `openai/o1-pro`, `openai/o1-pro-2025-03-19`, `openai/o3`, `openai/o3-2025-04-16`, `openai/o3-mini`, `openai/o3-mini-2025-01-31`, `openai/o3-pro`, `openai/o3-pro-2025-06-10`, `openai/o3-deep-research`, `openai/o3-deep-research-2025-06-26`, `openai/o4-mini`, `openai/o4-mini-2025-04-16`, `openai/o4-mini-deep-research`, `openai/o4-mini-deep-research-2025-06-26`, `openai/codex-mini-latest`
* Search preview: `openai/gpt-4o-search-preview`, `openai/gpt-4o-search-preview-2025-03-11`, `openai/gpt-4o-mini-search-preview`, `openai/gpt-4o-mini-search-preview-2025-03-11`
* Legacy: `openai/babbage-002`, `openai/davinci-002`, `openai/ft:babbage-002`, `openai/ft:davinci-002`

## Nova

Amazon's Nova models are available via Amazon Bedrock, with regional variants using `us.`, `eu.`, `apac.`, and `global.` prefixes.

* Text: `bedrock/amazon.nova-micro-v1:0`, `bedrock/amazon.nova-lite-v1:0`, `bedrock/amazon.nova-pro-v1:0`, `bedrock/amazon.nova-2-lite-v1:0`, `bedrock/amazon.nova-2-pro-preview-20251202-v1:0`, `bedrock/us.amazon.nova-premier-v1:0`
* Image: `bedrock/amazon.nova-canvas-v1:0`, `bedrock/us.amazon.nova-canvas-v1:0`, `bedrock/1024-x-1024/50-steps/bedrock/amazon.nova-canvas-v1:0`
* Multimodal embeddings: `bedrock/amazon.nova-2-multimodal-embeddings-v1:0`

## Llama

Meta's Llama models are available via Amazon Bedrock. Llama 3.1+ models are also available with `us.` prefix; select models with `eu.` prefix.

* Llama 2: `bedrock/meta.llama2-13b-chat-v1`, `bedrock/meta.llama2-70b-chat-v1`
* Llama 3: `bedrock/meta.llama3-8b-instruct-v1:0`, `bedrock/meta.llama3-70b-instruct-v1:0`
* Llama 3.1: `bedrock/meta.llama3-1-8b-instruct-v1:0`, `bedrock/meta.llama3-1-70b-instruct-v1:0`, `bedrock/meta.llama3-1-405b-instruct-v1:0`
* Llama 3.2: `bedrock/meta.llama3-2-1b-instruct-v1:0`, `bedrock/meta.llama3-2-3b-instruct-v1:0`, `bedrock/meta.llama3-2-11b-instruct-v1:0`, `bedrock/meta.llama3-2-90b-instruct-v1:0`
* Llama 3.3: `bedrock/meta.llama3-3-70b-instruct-v1:0`
* Llama 4: `bedrock/meta.llama4-scout-17b-instruct-v1:0`, `bedrock/meta.llama4-maverick-17b-instruct-v1:0`

## Qwen

Alibaba's Qwen models are available via Amazon Bedrock.

* `bedrock/qwen.qwen3-32b-v1:0`
* `bedrock/qwen.qwen3-235b-a22b-2507-v1:0`
* `bedrock/qwen.qwen3-coder-30b-a3b-v1:0`
* `bedrock/qwen.qwen3-coder-480b-a35b-v1:0`
* `bedrock/qwen.qwen3-coder-next`
* `bedrock/qwen.qwen3-next-80b-a3b`
* `bedrock/qwen.qwen3-vl-235b-a22b`

## Mistral

Mistral models are available via Amazon Bedrock.

* Chat: `bedrock/mistral.mistral-7b-instruct-v0:2`, `bedrock/mistral.mixtral-8x7b-instruct-v0:1`, `bedrock/mistral.mistral-small-2402-v1:0`, `bedrock/mistral.mistral-large-2402-v1:0`, `bedrock/mistral.mistral-large-2407-v1:0`, `bedrock/mistral.mistral-large-3-675b-instruct`, `bedrock/mistral.magistral-small-2509`
* Ministral: `bedrock/mistral.ministral-3-3b-instruct`, `bedrock/mistral.ministral-3-8b-instruct`, `bedrock/mistral.ministral-3-14b-instruct`
* Code: `bedrock/mistral.devstral-2-123b`
* Vision: `bedrock/eu.mistral.pixtral-large-2502-v1:0`, `bedrock/us.mistral.pixtral-large-2502-v1:0`
* Audio: `bedrock/mistral.voxtral-mini-3b-2507`, `bedrock/mistral.voxtral-small-24b-2507`

## Image Generation

**Stability AI** — available via Amazon Bedrock

* Generation: `bedrock/stability.stable-diffusion-xl-v0` (512x512 and max-x-max, 50-steps and max-steps variants), `bedrock/stability.stable-diffusion-xl-v1` (1024x1024, 50-steps and max-steps variants), `bedrock/stability.sd3-large-v1:0`, `bedrock/stability.sd3-5-large-v1:0`, `bedrock/stability.stable-image-core-v1:0`, `bedrock/stability.stable-image-core-v1:1`, `bedrock/stability.stable-image-ultra-v1:0`, `bedrock/stability.stable-image-ultra-v1:1`
* Editing: `bedrock/stability.stable-image-control-sketch-v1:0`, `bedrock/stability.stable-image-control-structure-v1:0`, `bedrock/stability.stable-image-inpaint-v1:0`, `bedrock/stability.stable-image-erase-object-v1:0`, `bedrock/stability.stable-image-remove-background-v1:0`, `bedrock/stability.stable-image-search-recolor-v1:0`, `bedrock/stability.stable-image-search-replace-v1:0`, `bedrock/stability.stable-image-style-guide-v1:0`, `bedrock/stability.stable-outpaint-v1:0`, `bedrock/stability.stable-style-transfer-v1:0`
* Upscaling: `bedrock/stability.stable-conservative-upscale-v1:0`, `bedrock/stability.stable-creative-upscale-v1:0`, `bedrock/stability.stable-fast-upscale-v1:0`

**DALL-E & GPT Image** — available via OpenAI

* DALL-E 2: `openai/dall-e-2`, `openai/256-x-256/dall-e-2`, `openai/512-x-512/dall-e-2`, `openai/1024-x-1024/dall-e-2`
* DALL-E 3: `openai/dall-e-3`, `openai/standard/1024-x-1024/dall-e-3`, `openai/standard/1024-x-1792/dall-e-3`, `openai/standard/1792-x-1024/dall-e-3`, `openai/hd/1024-x-1024/dall-e-3`, `openai/hd/1024-x-1792/dall-e-3`, `openai/hd/1792-x-1024/dall-e-3`
* GPT Image: `openai/gpt-image-1`, `openai/gpt-image-1-mini`, `openai/gpt-image-1.5`, `openai/gpt-image-1.5-2025-12-16`, `openai/gpt-image-2`, `openai/gpt-image-2-2026-04-21`, `openai/chatgpt-image-latest`. Also available across `low`, `medium`, `high`, and `standard` quality tiers in `1024-x-1024`, `1024-x-1536`, and `1536-x-1024` resolutions.
* Video: `openai/sora-2`, `openai/sora-2-pro`, `openai/sora-2-pro-high-res`

**Amazon Titan** — available via Amazon Bedrock

* `bedrock/amazon.titan-image-generator-v1`, `bedrock/amazon.titan-image-generator-v2`, `bedrock/amazon.titan-image-generator-v2:0`

## Audio & Speech

Available via OpenAI.

* Text-to-speech: `openai/tts-1`, `openai/tts-1-1106`, `openai/tts-1-hd`, `openai/tts-1-hd-1106`, `openai/gpt-4o-mini-tts`, `openai/gpt-4o-mini-tts-2025-03-20`, `openai/gpt-4o-mini-tts-2025-12-15`, `openai/gpt-audio`, `openai/gpt-audio-1.5`, `openai/gpt-audio-2025-08-28`, `openai/gpt-audio-mini`, `openai/gpt-audio-mini-2025-10-06`, `openai/gpt-audio-mini-2025-12-15`
* Transcription: `openai/whisper-1`, `openai/gpt-4o-transcribe`, `openai/gpt-4o-transcribe-diarize`, `openai/gpt-4o-mini-transcribe`, `openai/gpt-4o-mini-transcribe-2025-03-20`, `openai/gpt-4o-mini-transcribe-2025-12-15`
* Audio preview: `openai/gpt-4o-audio-preview`, `openai/gpt-4o-audio-preview-2024-12-17`, `openai/gpt-4o-audio-preview-2025-06-03`, `openai/gpt-4o-mini-audio-preview`, `openai/gpt-4o-mini-audio-preview-2024-12-17`
* Realtime: `openai/gpt-4o-realtime-preview`, `openai/gpt-4o-realtime-preview-2024-12-17`, `openai/gpt-4o-realtime-preview-2025-06-03`, `openai/gpt-4o-mini-realtime-preview`, `openai/gpt-4o-mini-realtime-preview-2024-12-17`, `openai/gpt-realtime`, `openai/gpt-realtime-1.5`, `openai/gpt-realtime-2`, `openai/gpt-realtime-2025-08-28`, `openai/gpt-realtime-mini`, `openai/gpt-realtime-mini-2025-10-06`, `openai/gpt-realtime-mini-2025-12-15`
* Also available via Amazon Bedrock: `bedrock/mistral.voxtral-mini-3b-2507`, `bedrock/mistral.voxtral-small-24b-2507`

## Embeddings

* Via OpenAI: `openai/text-embedding-ada-002`, `openai/text-embedding-ada-002-v2`, `openai/text-embedding-3-small`, `openai/text-embedding-3-large`
* Via Amazon Bedrock: `bedrock/amazon.titan-embed-text-v1`, `bedrock/amazon.titan-embed-text-v2:0`, `bedrock/amazon.titan-embed-image-v1`, `bedrock/amazon.nova-2-multimodal-embeddings-v1:0`, `bedrock/cohere.embed-english-v3`, `bedrock/cohere.embed-multilingual-v3`, `bedrock/cohere.embed-v4:0`, `bedrock/twelvelabs.marengo-embed-2-7-v1:0` (also `us.`, `eu.`)

## Reranking

* Via Amazon Bedrock: `bedrock/amazon.rerank-v1:0`, `bedrock/cohere.rerank-v3-5:0`

## Moderation

* Via OpenAI: `openai/text-moderation-007`, `openai/text-moderation-latest`, `openai/text-moderation-stable`, `openai/omni-moderation-2024-09-26`, `openai/omni-moderation-latest`

## Additional Models

* **DeepSeek** — via Amazon Bedrock: `bedrock/deepseek.v3-v1:0`, `bedrock/deepseek.v3.2`, `bedrock/us.deepseek.r1-v1:0`, `bedrock/us.deepseek.v3.2`, `bedrock/eu.deepseek.v3.2`
* **Gemma (Google)** — via Amazon Bedrock: `bedrock/google.gemma-3-4b-it`, `bedrock/google.gemma-3-12b-it`, `bedrock/google.gemma-3-27b-it`
* **Kimi (Moonshot AI)** — via Amazon Bedrock: `bedrock/moonshot.kimi-k2-thinking`, `bedrock/moonshotai.kimi-k2-thinking`, `bedrock/moonshotai.kimi-k2.5`
* **MiniMax** — via Amazon Bedrock: `bedrock/minimax.minimax-m2`, `bedrock/minimax.minimax-m2.1`, `bedrock/minimax.minimax-m2.5`
* **Nemotron (NVIDIA)** — via Amazon Bedrock: `bedrock/nvidia.nemotron-nano-9b-v2`, `bedrock/nvidia.nemotron-nano-12b-v2`, `bedrock/nvidia.nemotron-nano-3-30b`, `bedrock/nvidia.nemotron-super-3-120b`
* **Palmyra (Writer)** — via Amazon Bedrock: `bedrock/writer.palmyra-x4-v1:0`, `bedrock/writer.palmyra-x5-v1:0` (also `us.`)
* **Pegasus (TwelveLabs)** — via Amazon Bedrock: `bedrock/twelvelabs.pegasus-1-2-v1:0` (also `us.`, `eu.`)
* **GLM (ZAI / Zhipu AI)** — via Amazon Bedrock: `bedrock/zai.glm-4.7`, `bedrock/zai.glm-4.7-flash`, `bedrock/zai.glm-5`
* **Jamba (AI21 Labs)** — via Amazon Bedrock: `bedrock/ai21.j2-mid-v1`, `bedrock/ai21.j2-ultra-v1`, `bedrock/ai21.jamba-instruct-v1:0`, `bedrock/ai21.jamba-1-5-mini-v1:0`, `bedrock/ai21.jamba-1-5-large-v1:0`
* **Command (Cohere)** — via Amazon Bedrock: `bedrock/cohere.command-light-text-v14`, `bedrock/cohere.command-text-v14`, `bedrock/cohere.command-r-v1:0`, `bedrock/cohere.command-r-plus-v1:0`
* **Titan (Amazon)** — via Amazon Bedrock: `bedrock/amazon.titan-text-express-v1`, `bedrock/amazon.titan-text-lite-v1`, `bedrock/amazon.titan-text-premier-v1:0`
* **OpenAI OSS (via Bedrock)**: `bedrock/openai.gpt-oss-20b-1:0`, `bedrock/openai.gpt-oss-120b-1:0`, `bedrock/openai.gpt-oss-safeguard-20b`, `bedrock/openai.gpt-oss-safeguard-120b`


# MCP Gateway
Source: https://www.aptible.com/docs/mcp-gateway

Govern your team and agents' access to MCP servers through a single, audited endpoint.

## Overview

<Frame>
  <img alt="MCP Gateway Overview" />
</Frame>

<Tip>
  The MCP Gateway is in early access and available as a standalone product. No existing Aptible infrastructure required. [Join the waitlist →](https://www.aptible.com/mcp-gateway) and our team will reach out!
</Tip>

Aptible's MCP Gateway gives you control over how your team and AI agents access MCP servers. Instead of connecting MCP servers directly to your AI client (like Claude Code or Claude Desktop), you route those calls through the gateway, where access is enforced and every tool call is logged.

The gateway sits between your agents and your upstream MCP servers. When an agent makes a tool call, the gateway checks whether that caller is allowed to use that tool, forwards the request if they are, and writes an audit log entry regardless.

Three concepts control how this works:

* **Servers & Tools:** the upstream MCP services you register with the gateway, and the individual tools each one exposes
* **Access Control:** grants that scope which tools a user or robot can call
* **Audit Logging:** a full record of every tool call routed through the gateway

When an agent authenticates and calls a tool, the gateway resolves the caller's grants in real time and either forwards the call or rejects it.

### What is MCP?

Model Context Protocol (MCP) is an open standard that lets AI agents discover and call external tools at runtime, such as reading files, querying a database, creating a GitHub issue, or searching your knowledge base. Instead of hardcoding integrations into your AI client, MCP lets any compatible client connect to any compatible server using a common protocol.

The problem is that MCP servers run with real credentials and can take real actions. Without a control layer, there is no way to enforce who can call what, no record of what happened, and no way to prevent a user or agent from wiring in a server your organization never approved. An unmanaged MCP setup also has a meaningful prompt injection risk: a malicious tool description or server response can instruct an agent to call tools outside its intended scope.

The MCP Gateway addresses these problems at the proxy layer, where restricted tools are structurally unavailable, not just hidden from the client's view.

## Features

### Security Model

The MCP Gateway is built on the principle that AI agents should not have more access than they need and that every action they take should be recorded.

| Principle                  | How it works                                                                                                                                              |
| -------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Deny by default**        | No user or agent can call a tool unless a grant explicitly allows it. There is no implicit access.                                                        |
| **Per-tool scoping**       | Grants target individual tools, not just servers. A developer can get read access to GitHub without getting write access.                                 |
| **Full audit trail**       | Every tool call is logged: who called it, which tool, what arguments, when, and from which IP, regardless of whether it succeeded.                        |
| **Isolated credentials**   | Agents authenticate with scoped tokens that can be rotated or revoked at any time without touching upstream server credentials.                           |
| **Managed deployment**     | MDM-delivered configuration ensures all MCP traffic flows through the gateway. Users cannot add unmanaged servers or swap in personal tokens.             |
| **Blast radius reduction** | Because grants are narrow by design, a compromised agent or a prompt injection attack can only reach the tools that identity was already allowed to call. |

### Access Control

<Frame>
  <img alt="MCP Grants" />
</Frame>

Grants let you give each user or agent access to exactly the tools they need. For example, a developer connecting to your GitHub server might get read access to repositories but not the ability to merge pull requests.

Robot accounts and API keys extend the same model to automated pipelines and agents. Issue a scoped token per identity and rotate or revoke it at any time without touching your agent code.

[Learn more about Access Control →](/docs/mcp-gateway/access-control)

### Audit Logging

<Frame>
  <img alt="MCP Audit Logs" />
</Frame>

Every tool call is logged: who called it, which tool, what arguments were passed, when, and from which IP. Logs are available in the dashboard and can be filtered by user, server, tool, or date range. Account owners see all calls across the organization; individual users see their own.

[Learn more about Audit Logging →](/docs/mcp-gateway/audit-logs)

### Works with any MCP-compatible client

<Frame>
  <img alt="MCP Servers" />
</Frame>

The gateway exposes a standard MCP endpoint, so any MCP-compatible AI client (Claude Desktop, Claude Code, custom agents, or your own tooling) can connect using a bearer token. Common upstream servers customers wire up through the gateway include GitHub, Notion, Sentry, Short, and Granola, but any server that speaks MCP will work.

[Learn more about Servers & Tools →](/docs/mcp-gateway/servers)

### Deploying with MDM

MDM is how you enforce that all MCP traffic flows through the gateway.

Both Claude Desktop and Claude Code read their MCP server configuration from a JSON file on disk. Your MDM pushes that file to every machine, pre-populated with your gateway endpoint and a scoped token. Because MDM-managed files can be locked, users cannot add unmanaged servers or replace the token with a personal one.

Once deployed, every MCP tool call from that machine is authenticated with the org token, checked against the user's grants, and written to the audit log.

## Support and Feedback

We'd love to hear from you as you use the MCP Gateway. If you have questions, run into issues, or have feature requests, [contact us](https://app.aptible.com/support).


# Access Control
Source: https://www.aptible.com/docs/mcp-gateway/access-control

Control who can call which tools using grants and membership.

## Overview

Access in the MCP Gateway is built on two concepts:

* **[Grants](/docs/mcp-gateway/grants):** records that specify a set of tools and the users or agents allowed to call them. No grant, no access.
* **[Membership](/docs/mcp-gateway/membership):** users, robots, and API keys that can be attached to grants. Robots and API keys extend access to automated pipelines and agents.

When an agent calls a tool, the gateway checks whether a grant exists for that caller on that tool, and either forwards the call or rejects it. Access is deny-by-default. No implicit access is inherited.

<Info>
  Account Owner or Admin permission is required to manage grants and add or manage users and robots. Any user can create their own API key.
</Info>

<CardGroup>
  <Card title="Grants" href="/mcp-gateway/grants">
    Create and manage grants to scope tool access per user or agent.
  </Card>

  <Card title="Membership" href="/mcp-gateway/membership">
    Set up robots and API keys for non-human callers.
  </Card>
</CardGroup>


# Audit Logging
Source: https://www.aptible.com/docs/mcp-gateway/audit-logs

Review every tool call that flows through the MCP Gateway.

## Overview

<Frame>
  <img alt="MCP Audit Logs 1" />
</Frame>

Every tool call routed through the MCP Gateway is logged automatically. No configuration required.

In the Aptible dashboard, navigate to **MCP > Audit Logs**.

<Info>
  Account owners can see all tool calls across the organization. End users see only their own activity.
</Info>

## What Gets Logged

Each log entry captures:

* **Time:** when the call was made
* **Server:** the server the tool belongs to
* **Tool:** the full namespaced tool name (e.g. `github_get_file_contents`)
* **Args:** the number of arguments passed (arguments are stored encrypted)
* **User Agent:** the MCP client making the request

Arguments are stored encrypted at rest. The log entry shows the argument count; the full argument values are available when you expand a row.

## Filter Logs

Use the filter controls at the top of the page to narrow the log view:

* **From / To:** date and time range pickers
* **Server:** dropdown to filter to a specific server
* **Tool:** dropdown to filter to a specific tool

## Retention and Export

Audit logs are retained within the dashboard. To export logs or send them to an external destination for long-term retention, [contact Aptible Support](https://app.aptible.com/support).

## Related

<CardGroup>
  <Card title="Grants" href="/mcp-gateway/grants">
    Control which tools each user or agent can call.
  </Card>

  <Card title="Membership" href="/mcp-gateway/membership">
    Manage the users, robots, and API keys that appear in logs.
  </Card>
</CardGroup>


# Connecting to MCP Gateway
Source: https://www.aptible.com/docs/mcp-gateway/connect

Get your MCP client talking to the gateway in two steps: create an API key, then point your client at the gateway URL.

## Overview

To use the MCP Gateway with your AI client (Claude Desktop, Claude Code, or any MCP-compatible tool), you need two things:

1. A personal API key to authenticate as yourself
2. Your client pointed at `https://mcp-gateway.aptible.com`

<Tip>
  Your admin handles registering servers, setting up grants, and deciding which tools you have access to. Once that's done, this is all you need to do.
</Tip>

## Getting Started

<Steps>
  <Step title="Create an API Key">
    In the Aptible dashboard, navigate to **MCP > API Keys** and create a new key. Copy the token. You won't be able to see it again after closing the dialog.

    <Frame>
      <img alt="MCP API Key" />
    </Frame>
  </Step>

  <Step title="Add the Gateway as an MCP Server">
    Point your MCP client at `https://mcp-gateway.aptible.com` and pass your API key as a bearer token in the `Authorization` header.

    <Tabs>
      <Tab title="Claude Desktop">
        Open your Claude Desktop config file (`~/Library/Application Support/Claude/claude_desktop_config.json` on macOS) and add an entry under `mcpServers`:

        ```json theme={null}
        {
          "mcpServers": {
            "aptible": {
              "url": "https://mcp-gateway.aptible.com",
              "headers": {
                "Authorization": "Bearer <your-api-key>"
              }
            }
          }
        }
        ```

        Save the file and restart Claude Desktop.
      </Tab>

      <Tab title="Claude Code">
        Run the following command to add the gateway as an MCP server:

        ```bash theme={null}
        claude mcp add aptible https://mcp-gateway.aptible.com \
          --header "Authorization: Bearer <your-api-key>"
        ```
      </Tab>

      <Tab title="Other clients">
        Configure your client to connect to `https://mcp-gateway.aptible.com` and pass your API key as a bearer token:

        ```text theme={null}
        Authorization: Bearer <your-api-key>
        ```

        Refer to your client's documentation for where to set custom headers.
      </Tab>
    </Tabs>
  </Step>
</Steps>

## Using the MCP Gateway

Once connected, your AI client will discover the tools available to you through the gateway. From that point, using the gateway is transparent. You call tools the same way you would with any MCP server, and the gateway handles routing, access checking, and logging in the background.

To see the full list of tools you have access to, navigate to **MCP > My Tools** in the Aptible dashboard.

<Frame>
  <img alt="MCP My Tools" />
</Frame>

If a tool you expect isn't showing up, check with your admin that you've been added to the appropriate grant.

## Related

<CardGroup>
  <Card title="User API Keys" href="/mcp-gateway/membership#user-api-keys">
    Manage your personal API keys.
  </Card>

  <Card title="Audit Logging" href="/mcp-gateway/audit-logs">
    See your tool call history.
  </Card>
</CardGroup>


# Grants
Source: https://www.aptible.com/docs/mcp-gateway/grants

Scope which tools each user or agent can call using grants.

## Overview

A grant is the record that authorizes a set of members to call a specific set of tools. If no grant exists for a caller on a given tool, the call is rejected. There is no implicit access.

<Info>
  Account Owner or Admin permission is required to create and manage grants.
</Info>

A grant has two parts:

* **Users & Robots:** the people and automated accounts attached to the grant
* **Tools Allowed:** the specific tools members can call, selected per server

<Frame>
  <img alt="MCP Grants" />
</Frame>

## Create a Grant

<AccordionGroup>
  <Accordion title="Create a new grant (Admins only)">
    <Steps>
      <Step title="Open the Grants page">
        In the Aptible dashboard, navigate to **MCP > Grants** and click **New Grant**.
      </Step>

      <Step title="Name the grant">
        Enter a **Grant Name** that describes the scope (e.g. `GitHub (Eng)`, `Toolshed (Owners)`).
      </Step>

      <Step title="Add users and robots">
        Under **Users & Robots**, search for and select the members who should receive this grant. Both user accounts and robot accounts appear in this list.
      </Step>

      <Step title="Choose tools and save">
        Under **Tools Allowed**, expand the servers you want to include. Select individual tools, or check **Select all tools (wildcard \*)** to allow all current and future tools on that server. Click **Save** to apply the grant.
      </Step>
    </Steps>
  </Accordion>
</AccordionGroup>

Tools are grouped by server and by category (e.g. read-only vs. write). The count badge next to each server shows how many tools are selected out of how many are available.

## Related

<CardGroup>
  <Card title="Membership" href="/mcp-gateway/membership">
    Create robots and API keys to add to your grants.
  </Card>

  <Card title="Audit Logging" href="/mcp-gateway/audit-logs">
    See every tool call made by grant members.
  </Card>
</CardGroup>


# Membership
Source: https://www.aptible.com/docs/mcp-gateway/membership

Add users, robots, and API keys to grants so they can call tools through the gateway.

## Overview

Membership is how identities get attached to [grants](/docs/mcp-gateway/grants). The gateway supports three types of members:

| Type        | What it is                                   | How it authenticates          |
| ----------- | -------------------------------------------- | ----------------------------- |
| **User**    | A person with an Aptible account             | Session token or user API key |
| **Robot**   | A non-human account for pipelines and agents | Robot API key (bearer token)  |
| **API Key** | A scoped token tied to a user account        | Bearer token                  |

All three types are added to grants the same way and are subject to the same access rules. Every call they make is written to the [audit log](/docs/mcp-gateway/audit-logs).

<Info>
  Account Owner or Admin permission is required to add and manage users and robots. Any user can create their own API key.
</Info>

## Robots

Robots are non-human accounts for automated pipelines and agents. They authenticate to the gateway with a bearer token and are attached to grants the same way user accounts are. Everything a robot calls is checked against its grants and written to the audit log.

<Frame>
  <img alt="MCP Robots" />
</Frame>

<AccordionGroup>
  <Accordion title="Create a robot (Admins only)">
    <Steps>
      <Step title="Open the Robots page">
        In the Aptible dashboard, navigate to **MCP > Robots**.
      </Step>

      <Step title="Create the robot">
        Enter a name and click **Create Robot User**.
      </Step>

      <Step title="Generate an API key">
        Open the robot and click **+ Create API Key** to generate a token.
      </Step>
    </Steps>
  </Accordion>
</AccordionGroup>

Robots appear in the **Users & Robots** selector on the Grant Details panel. Add them to a grant the same way you'd add a user.

## User API Keys

Any user can create an API key to authenticate to the gateway without using their Aptible session token. In the Aptible dashboard, navigate to **MCP > API Keys** to create and manage them.

<Frame>
  <img alt="MCP API Key" />
</Frame>

## Authenticating to the Gateway

Both robot tokens and user API keys are passed as a bearer token in the `Authorization` header when connecting an MCP client to the gateway endpoint:

```text theme={null}
Authorization: Bearer <token>
```

For a full walkthrough of how to connect your MCP client to the gateway, see [Connecting to MCP Gateway](/docs/mcp-gateway/connect).

## Related

<CardGroup>
  <Card title="Connecting to MCP Gateway" href="/mcp-gateway/connect">
    Step-by-step guide for end users to get connected.
  </Card>

  <Card title="Grants" href="/mcp-gateway/grants">
    Attach members to a grant to give them tool access.
  </Card>
</CardGroup>


# Servers & Tools
Source: https://www.aptible.com/docs/mcp-gateway/servers

Register upstream MCP servers with the gateway so agents can call their tools.

## Overview

<Frame>
  <img alt="MCP Servers" />
</Frame>

There are two core concepts on this page:

* **Servers** are the upstream MCP services registered with the gateway: GitHub, Notion, an internal API, or any service that speaks MCP. A server holds credentials, exposes a URL, and defines what capabilities are available.
* **Tools** are the individual functions a server exposes: `list_repos`, `create_issue`, `search_documents`, and so on. Tools are what agents actually call. Connect a server and its tools are discovered and kept in sync automatically.

One server exposes many tools. Access control, audit logging, and grants all operate at the tool level.

<Info>
  Account Owner or Admin permission is required to manage and modify servers and tools.
</Info>

## Connecting a Server

<AccordionGroup>
  <Accordion title="Register a new server (Admins only)">
    <Steps>
      <Step title="Open the Servers tab">
        In the MCP Management Console, navigate to the **Servers** tab and click **New Server**.
      </Step>

      <Step title="Name the server">
        Enter a name for the server. Names must start with a letter and contain only lowercase letters, digits, hyphens, and underscores (e.g. `github`, `internal-api`). The name becomes the namespace prefix for all tools on this server. A server named `github` with a tool called `list_repos` becomes `github_list_repos`.
      </Step>

      <Step title="Enter the server URL">
        Enter the endpoint your upstream MCP server is running on.
      </Step>

      <Step title="Select the transport type">
        Most servers use **Streamable HTTP**. Select **SSE** if your server requires it.
      </Step>

      <Step title="Configure server authentication">
        Choose the credential mode (**shared** or **personal**) and the auth type that matches how your upstream server expects to be authenticated. See [Server Authentication](#server-authentication) below.

        Click **Save**. Aptible connects to the server and discovers its available tools.
      </Step>
    </Steps>
  </Accordion>
</AccordionGroup>

## Server Authentication

Server authentication controls how the gateway talks to your upstream MCP server, separate from how end users authenticate to the gateway (see [Membership](/docs/mcp-gateway/membership) for that). It comes down to two choices: **who** the credentials belong to, and **how** they're presented to the upstream server.

### Credential Mode

| Mode         | How it works                                                                                      | When to use                                                                                       |
| ------------ | ------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------- |
| **Shared**   | A single set of credentials is used for every call the gateway routes through this server.        | Service accounts, internal APIs, or servers where the whole team acts as one identity.            |
| **Personal** | Each user connects with their own credentials. Calls use that user's credentials on the upstream. | User-scoped services like GitHub, Notion, or Granola where actions should be attributed per user. |

Shared-mode credentials are configured by account owners and admins only. Personal-mode servers show a **Connect** button for users who haven't yet connected, and a **Reconnect** button when re-authorization is needed. The **Auth** column on the Servers list shows both the credential mode and auth type (e.g. `oauth / personal`, `bearer / shared`).

### Auth Type

| Auth type          | When to use                                                                           |
| ------------------ | ------------------------------------------------------------------------------------- |
| **None**           | The upstream server requires no authentication.                                       |
| **Bearer**         | The server accepts a static bearer token in the `Authorization` header.               |
| **Custom headers** | The server requires one or more custom HTTP headers.                                  |
| **OAuth**          | The server supports OAuth 2.0 with PKCE. Aptible manages token refresh automatically. |

For **OAuth** servers, clicking **Save** (or **Connect** in personal mode) redirects you to the upstream service to complete authorization. Aptible performs Dynamic Client Registration automatically if the server supports it.

## Tool Discovery

After a server is saved and authorized, Aptible fetches its list of available tools. Each tool is namespaced under the server name: `github_list_repos`, `notion_search`, etc. The **Tools** column on the Servers list shows the count of discovered tools.

Tool definitions refresh automatically. If a server shows **Re-authorize**, the gateway's credentials need to be renewed before tool calls will succeed.

### View Your Tools

<Frame>
  <img alt="MCP My Tools" />
</Frame>

Navigate to **MCP > My Tools** to see every tool available to you based on your grant memberships, along with the server it belongs to, its parameters, and a description.

## Next Steps

Connecting a server makes its tools available in the gateway but doesn't grant anyone access to them.

<CardGroup>
  <Card title="Grants" href="/mcp-gateway/grants">
    Scope which tools each user or agent can call.
  </Card>

  <Card title="Membership" href="/mcp-gateway/membership">
    Set up robots and API keys for automated pipelines.
  </Card>
</CardGroup>


# aptible apps
Source: https://www.aptible.com/docs/reference/aptible-cli/cli-commands/cli-apps



This command lists [Apps](/docs/core-concepts/apps/overview) in an [Environment](/docs/core-concepts/architecture/environments).

# Synopsis

```
Usage:
  aptible apps

Options:
  --env, [--environment=ENVIRONMENT]
```

# JSON Output

When using `APTIBLE_OUTPUT_FORMAT=json`, the output includes additional deployment-related fields:

| Field                       | Description                                         |
| --------------------------- | --------------------------------------------------- |
| `docker_image`              | The Docker image configured for direct image deploy |
| `private_registry_username` | Username for private registry authentication        |
| `private_registry_password` | Password for private registry authentication        |

To view deployment settings for a specific app, use [`aptible apps:settings`](/docs/reference/aptible-cli/cli-commands/cli-apps-settings).


# aptible apps:create
Source: https://www.aptible.com/docs/reference/aptible-cli/cli-commands/cli-apps-create



This command creates a new [App](/docs/core-concepts/apps/overview).

# Synopsis

```
Usage:
  aptible apps:create HANDLE

Options:
  --env, [--environment=ENVIRONMENT]

```


# aptible apps:deprovision
Source: https://www.aptible.com/docs/reference/aptible-cli/cli-commands/cli-apps-deprovision



This command deprovisions an [App](/docs/core-concepts/apps/overview).

# Synopsis

```
Usage:
  aptible apps:deprovision [--app APP]

Options:
      [--app=APP]
  --env, [--environment=ENVIRONMENT]
  -r, [--remote=REMOTE]
```


# aptible apps:rename
Source: https://www.aptible.com/docs/reference/aptible-cli/cli-commands/cli-apps-rename



This command renames [App](/docs/core-concepts/apps/overview) handles. For the change to take effect, the App must be restarted.

# Synopsis

```
Usage:
  aptible apps:rename OLD_HANDLE NEW_HANDLE [--environment ENVIRONMENT_HANDLE]

Options:
  --env, [--environment=ENVIRONMENT]
```


# aptible apps:scale
Source: https://www.aptible.com/docs/reference/aptible-cli/cli-commands/cli-apps-scale



This command [scales](/docs/core-concepts/scaling/overview) App [Services](/docs/core-concepts/apps/deploying-apps/services) up or down.

# Synopsis

```
Usage:
  aptible apps:scale [--app APP] SERVICE [--container-count COUNT] [--container-size SIZE_MB] [--container-profile PROFILE]

Options:
      [--app=APP]
  --env, [--environment=ENVIRONMENT]
  -r, [--remote=REMOTE]
      [--container-count=N]
      [--container-size=N]
      [--container-profile=PROFILE]
```

# Examples

```shell theme={null}
# Scale a service up or down
aptible apps:scale --app "$APP_HANDLE" SERVICE \
        --container-count COUNT \
        --container-size SIZE_MB

# Restart a service by scaling to its current count
aptible apps:scale --app "$APP_HANDLE" SERVICE \
        --container-count CURRENT_COUNT
```

#### Container Sizes (MB)

**All container profiles** support the following sizes: 512, 1024, 2048, 4096, 7168, 15360, 30720

The following profiles offer additional supported sizes:

* **General Purpose (M) - Legacy, General Purpose(M) and Memory Optimized(R)** - **Legacy**: 61440, 153600, 245760
* **CPU Optimized (C)**: 61440, 153600, 245760, 376832
* **Memory Optimized (R)**: 61440, 153600, 245760, 376832, 507904, 770048


# aptible apps:settings
Source: https://www.aptible.com/docs/reference/aptible-cli/cli-commands/cli-apps-settings



This command displays deployment settings for an [App](/docs/core-concepts/apps/overview), including the configured Docker image and private registry credentials.

# Synopsis

```
Usage:
  aptible apps:settings HANDLE

Options:
  --env, [--environment=ENVIRONMENT]
```

# Examples

View deployment settings for an app:

```shell theme={null}
aptible apps:settings my-app --env production
```

Example output:

```
Id: 20120
Handle: my-app
Created At: 2020-05-01 20:25:58 UTC
Environment: production
Status: provisioned
Git Remote: git@beta.aptible.com:production/my-app.git
Last Deploy Operation: 97890638
Docker Image: quay.io/myorg/myapp:latest
Private Registry Username: registryuser
Private Registry Password: registrypass
```

Get deployment settings as JSON for automation:

```shell theme={null}
APTIBLE_OUTPUT_FORMAT=json aptible apps:settings my-app --env production
```

Example JSON output:

```json theme={null}
{
  "id": 20120,
  "handle": "my-app",
  "created_at": "2020-05-01 20:25:58 UTC",
  "environment": {
    "id": 3369,
    "handle": "production",
    "created_at": "2019-10-29 17:12:39 UTC"
  },
  "status": "provisioned",
  "git_remote": "git@beta.aptible.com:production/my-app.git",
  "last_deploy_operation": {
    "id": 97890638,
    "status": "succeeded",
    "git_ref": null,
    "user_email": "deploy@example.com",
    "created_at": "2025-12-01 17:21:16 UTC"
  },
  "docker_image": "quay.io/myorg/myapp:latest",
  "private_registry_username": "registryuser",
  "private_registry_password": "registrypass"
}
```

# Output Fields

| Field                       | Description                                         |
| --------------------------- | --------------------------------------------------- |
| `id`                        | The app's unique identifier                         |
| `handle`                    | The app's handle (name)                             |
| `created_at`                | When the app was created                            |
| `environment`               | The environment containing the app                  |
| `status`                    | Current app status (e.g., `provisioned`)            |
| `git_remote`                | Git remote URL for git-based deployments            |
| `last_deploy_operation`     | Details about the most recent deploy operation      |
| `docker_image`              | The Docker image configured for direct image deploy |
| `private_registry_username` | Username for private registry authentication        |
| `private_registry_password` | Password for private registry authentication        |


# aptible backup:list
Source: https://www.aptible.com/docs/reference/aptible-cli/cli-commands/cli-backup-list



This command lists all [Database Backups](/docs/core-concepts/managed-databases/managing-databases/database-backups) for a given [Database](/docs/core-concepts/managed-databases/overview).

<Note>
  The option, `max-age`, defaults to effectively unlimited (99y years) lookback. For performance reasons, you may want to specify an appropriately narrow period for your use case, like `3d` or `2w`.
</Note>

## Synopsis

```
Usage:
  aptible backup:list DB_HANDLE

Options:
  --env, [--environment=ENVIRONMENT]
  [--max-age=MAX_AGE]          # Limit backups returned (example usage: 1w, 1y, etc.)
                               # Default: 99y

```

# Examples

```shell theme={null}
aptible backup:list "$DB_HANDLE"
```


# aptible backup:orphaned
Source: https://www.aptible.com/docs/reference/aptible-cli/cli-commands/cli-backup-orphaned



This command lists all [Final Database Backups](/docs/core-concepts/managed-databases/managing-databases/database-backups#retention-and-disposal).

<Note>
  The option, `max-age`, defaults to effectively unlimited (99y years) lookback. For performance reasons, you may want to specify an appropriately narrow period for your use case, like `1w` or `2m`.
</Note>

# Synopsis

```
Usage:
  aptible backup:orphaned

Options:
  --env, [--environment=ENVIRONMENT]
  [--max-age=MAX_AGE]          # Limit backups returned (example usage: 1w, 1y, etc.)
                               # Default: 99y
```


# aptible backup:purge
Source: https://www.aptible.com/docs/reference/aptible-cli/cli-commands/cli-backup-purge



This command permanently deletes a [Database Backup](/docs/core-concepts/managed-databases/managing-databases/database-backups) and its copies.

# Synopsis

```
Usage:
  aptible backup:purge BACKUP_ID
```


# aptible backup:restore
Source: https://www.aptible.com/docs/reference/aptible-cli/cli-commands/cli-backup-restore



This command is used to [restore from a Database Backup](/docs/core-concepts/managed-databases/managing-databases/database-backups#restoring-from-a-backup). This command creates a new database: it **does not overwrite your existing database.** In fact, it doesn't interact with your existing database at all. By default, all newly restored Databases are created as a 1GB [General Purpose (M) Container Profile](/docs/core-concepts/scaling/container-profiles#default-container-profile), however you can specify both container size and profile using the options.

You'll need the ID of an existing [Backup](/docs/core-concepts/managed-databases/managing-databases/database-backups) to use this command. You can find those IDs using the [`aptible backup:list`](/docs/reference/aptible-cli/cli-commands/cli-backup-list) command or through the Dashboard.

<Warning> Warning: If you are restoring a Backup of a GP3 volume, the new Database will be provisioned with the base [performance characteristics](/docs/core-concepts/scaling/database-scaling#throughput-performance): 3,000 IOPs and 125MB/s throughput. If the original Database's performance was scaled up, you may need to modify the restored Database if you wish to retain the performance of the source Database. </Warning>

# Synopsis

```
Usage:
  aptible backup:restore BACKUP_ID [--environment ENVIRONMENT_HANDLE] [--handle HANDLE] [--container-size SIZE_MB] [--disk-size SIZE_GB] [--container-profile PROFILE] [--iops IOPS] [--key-arn KEY_ARN]

Options:
  [--handle=HANDLE]            # a name to use for the new database
  --env, [--environment=ENVIRONMENT]  # a different environment to restore to
  [--container-size=N]
  [--size=N]
  [--disk-size=N]
  [--key-arn=KEY_ARN]
  [--container-profile=PROFILE]
  [--iops=IOPS]
```

# Examples

## Restore a Backup

```shell theme={null}
aptible backup:restore "$BACKUP_ID"
```

## Customize the new Database

You can also customize the new [Database](/docs/core-concepts/managed-databases/overview) that will be created from the Backup:

```shell theme={null}
aptible backup:restore "$BACKUP_ID" \
        --handle "$NEW_DATABASE_HANDLE" \
        --container-size "$CONTAINER_SIZE_MB" \
        --disk-size "$DISK_SIZE_GB"
```

If no handle is provided, it will default to `$DB_HANDLE-at-$BACKUP_DATE` where `$DB_HANDLE` is the handle of the Database the backup was taken from. Database handles must:

* Only contain lowercase alphanumeric characters,`.`, `_`, or `-`
* Be between 1 to 64 characters in length
* Be unique within their [Environment](/docs/core-concepts/architecture/environments)

Therefore, there are two situations where the default handle can be invalid:

* The handle is longer than 64 characters. The default handle will be 23 characters longer than the original Database's handle.
* The default handle is not unique within the Environment. Most likely, this would be caused by restoring the same backup to the same Environment multiple times.

## Restore to a different Environment

You can restore Backups across [Environments](/docs/core-concepts/architecture/environments) as long as they are hosted on the same type of [Stack](/docs/core-concepts/architecture/stacks). You can only restore Backups from a [Dedicated Stack](/docs/core-concepts/architecture/stacks#dedicated-stacks) in another Dedicated Stack and backups from a Shared Stack in another Shared Stack. Since Environments are globally unique, you do not need to specify the Stack in your command:

```shell theme={null}
aptible backup:restore "$BACKUP_ID" \
        --environment "$ENVIRONMENT_HANDLE"
```

## Disk Resizing Note

When specifying a disk size, note that the restored database can only be resized up (i.e., you cannot shrink your Database Disk). If you need to scale a Database Disk down, you can either dump and restore to a smaller Database or create a replica and failover. Refer to our [Supported Databases](/docs/core-concepts/managed-databases/supported-databases/overview) documentation to see if replication and failover is supported for your Database type.

#### Container Sizes (MB)

**General Purpose(M)**: 512, 1024, 2048, 4096, 7168, 15360, 30720, 61440, 153600, 245760


# aptible backup_retention_policy
Source: https://www.aptible.com/docs/reference/aptible-cli/cli-commands/cli-backup-retention-policy



This command shows the current
[backup retention policy](/docs/core-concepts/managed-databases/managing-databases/database-backups#automatic-backups)
for an [Environment](/docs/core-concepts/architecture/environments).

# Synopsis

```
Usage:
  aptible backup_retention_policy [ENVIRONMENT_HANDLE]

Show the current backup retention policy for the environment
```


# aptible backup_retention_policy:set
Source: https://www.aptible.com/docs/reference/aptible-cli/cli-commands/cli-backup-retention-policy-set



This command changes the
[backup retention policy](/docs/core-concepts/managed-databases/managing-databases/database-backups#automatic-backups)
for an [Environment](/docs/core-concepts/architecture/environments). Only the
specified attributes will be changed. The rest will reuse the current value.

# Synopsis

```
Usage:
  aptible backup_retention_policy:set [ENVIRONMENT_HANDLE] [--daily DAILY_BACKUPS] [--monthly MONTHLY_BACKUPS] [--yearly YEARLY_BACKUPS] [--make-copy|--no-make-copy] [--keep-final|--no-keep-final] [--force]

Options:
  [--daily=N]                        # Number of daily backups to retain
  [--monthly=N]                      # Number of monthly backups to retain
  [--yearly=N]                       # Number of yearly backups to retain
  [--make-copy], [--no-make-copy]    # If backup copies should be created
  [--keep-final], [--no-keep-final]  # If final backups should be kept when databases are deprovisioned
  [--force]                          # Do not prompt for confirmation if the new policy retains fewer backups than the current policy

Change the environment's backup retention policy
```


# aptible config
Source: https://www.aptible.com/docs/reference/aptible-cli/cli-commands/cli-config



This command prints an App's [Configuration](/docs/core-concepts/apps/deploying-apps/configuration) variables.

## Synopsis

```
Usage:
  aptible config [--app APP]

Options:
      [--app=APP]
  --env, [--environment=ENVIRONMENT]
  -r, [--remote=REMOTE]
```

> ❗️\*\* Warning:\*\* The output of this command is shell escaped, meaning if you have included any special characters, they will be shown with an escape character. For instance, if you set `"foo=bar?"` it will be displayed by [`aptible config`](/docs/reference/aptible-cli/cli-commands/cli-config) as `foo=bar\?`.

> If the values do not appear as you expect, you can further confirm how they are set using the JSON output\_format, or by inspecting the environment of your container directly using an [Ephemeral SSH Sessions](/docs/core-concepts/apps/connecting-to-apps/ssh-sessions).

# Examples

```shell theme={null}
aptible config --app "$APP_HANDLE"
```


# aptible config:add
Source: https://www.aptible.com/docs/reference/aptible-cli/cli-commands/cli-config-add



This command is an alias to [`aptible config:set`](/docs/reference/aptible-cli/cli-commands/cli-config-set).

# Synopsis

```javascript theme={null}
Usage:
  aptible config:add [--app APP] [VAR1=VAL1] [VAR2=VAL2] [...]

Options:
      [--app=APP]
  --env, [--environment=ENVIRONMENT]
  -r, [--remote=REMOTE]
```


# aptible config:get
Source: https://www.aptible.com/docs/reference/aptible-cli/cli-commands/cli-config-get



This command prints a single value from the App's [Configuration](/docs/core-concepts/apps/deploying-apps/configuration) variables.

# Synopsis

```
Usage:
  aptible config:get [--app APP] [VAR1]

Options:
      [--app=APP]
  --env, [--environment=ENVIRONMENT]
  -r, [--remote=REMOTE]
```

# Examples

```shell theme={null}
aptible config:get FORCE_SSL --app "$APP_HANDLE"
```


# aptible config:rm
Source: https://www.aptible.com/docs/reference/aptible-cli/cli-commands/cli-config-rm



This command is an alias to [`aptible config:unset`](/docs/reference/aptible-cli/cli-commands/cli-config-unset).

## Synopsis

```
Usage:
  aptible config:rm [--app APP] [VAR1][VAR2][...]

Options:
 [--app=APP]
 [--environment= ENVIRONMENT]
  -r, [--remote=REMOTE]
```


# aptible config:set
Source: https://www.aptible.com/docs/reference/aptible-cli/cli-commands/cli-config-set



This command sets [Configuration](/docs/core-concepts/apps/deploying-apps/configuration) variables for an [App](/docs/core-concepts/apps/overview).

# Synopsis

```
Usage:
  aptible config:set [--app APP] [VAR1=VAL1] [VAR2=VAL2] [...]

Options:
      [--app=APP]
  --env, [--environment=ENVIRONMENT]
  -r, [--remote=REMOTE]
```

# Examples

## Setting variables

```shell theme={null}
aptible config:set --app "$APP_HANDLE" \
        VARIABLE_1=VALUE_1 \
        VARIABLE_2=VALUE_2
```

## Setting a variable from a file

> 📘 Setting variables from a file is a convenient way to set complex variables that contain spaces, newlines, or other special characters.

```shell theme={null}
# This will read file.txt and set it as VARIABLE

aptible config:set --app "$APP_HANDLE" \
        "VARIABLE=$(cat file.txt)"
```

> ❗️ Warning: When setting variables from a file using PowerShell, you need to use `Get-Content` with the `-Raw` option to preserve newlines.

```shell theme={null}
aptible config:set --app "$APP_HANDLE" \
        VARIABLE=$(Get-Content file.txt -Raw)
```

## Deleting variables

To delete a variable, set it to an empty value:

```shell theme={null}
aptible config:set --app "$APP_HANDLE" \
        VARIABLE=
```


# aptible config:unset
Source: https://www.aptible.com/docs/reference/aptible-cli/cli-commands/cli-config-unset



This command is used to remove [Configuration](/docs/core-concepts/apps/deploying-apps/configuration) variables from an [App](/docs/core-concepts/apps/overview).

> 📘 Tip

> You can also use [`aptible config:set`](/docs/reference/aptible-cli/cli-commands/cli-config-set) to set and remove Configuration variables at the same time by passing an empty value:

```shell theme={null}
aptible config:set --app "$APP_HANDLE" \
        VAR_TO_ADD=some VAR_TO_REMOVE=
```

# Examples

```shell theme={null}
aptible config:unset --app "$APP_HANDLE" \
        VAR_TO_REMOVE
```

# Synopsis

```
Usage:
  aptible config:unset [--app APP] [VAR1] [VAR2] [...]

Options:
      [--app=APP]
  --env, [--environment=ENVIRONMENT]
  -r, [--remote=REMOTE]

Remove an ENV variable from an app
```


# aptible db:backup
Source: https://www.aptible.com/docs/reference/aptible-cli/cli-commands/cli-db-backup



This command is used to create [Database Backups](/docs/core-concepts/managed-databases/managing-databases/database-backups).

## Synopsis

```
Usage:
  aptible db:backup HANDLE

Options:
  --env, [--environment=ENVIRONMENT]
```

# Examples

```shell theme={null}
aptible db:backup "$DB_HANDLE"
```


# aptible db:clone
Source: https://www.aptible.com/docs/reference/aptible-cli/cli-commands/cli-db-clone



This command clones an existing Database.\
\
❗️ Warning: Consider using [`aptible backup:restore`](/docs/reference/aptible-cli/cli-commands/cli-backup-restore) instead.

> `db:clone` connects to your existing Database to copy data out and imports it into your new Database.

> This means `db:clone` creates load on your existing Database, and can be slow or disruptive if you have a lot of data to copy. It might even fail if the new Database is underprovisioned, since this is a resource-intensive process.

> This also means `db:clone` only works for a subset of [Supported Databases](/docs/core-concepts/managed-databases/supported-databases/overview) (those that allow for convenient import / export of data).

> In contrast, `backup:restore` instead uses a snapshot of your existing Database's disk, which means it doesn't affect your existing Database at all and supports all Aptible-supported Databases.

# Synopsis

```
Usage:
  aptible db:clone SOURCE DEST

Options:
  --env, [--environment=ENVIRONMENT]
```


# aptible db:create
Source: https://www.aptible.com/docs/reference/aptible-cli/cli-commands/cli-db-create



This command creates a new [Database](/docs/core-concepts/managed-databases/overview) using the General Purpose (M) container profile by default. The container profile can only be modified in the Aptible dashboard.

# Synopsis

```
Usage:
  aptible db:create HANDLE [--type TYPE] [--version VERSION] [--container-size SIZE_MB] [--container-profile PROFILE] [--disk-size SIZE_GB] [--iops IOPS] [--key-arn KEY_ARN]

Options:
  [--type=TYPE]
  [--version=VERSION]
  [--container-size=N]
  [--container-profile PROFILE]
                               # Default: m
  [--disk-size=N]
                               # Default: 10
  [--size=N]
  [--key-arn=KEY_ARN]
  [--iops=IOPS]
  --env, [--environment=ENVIRONMENT]
```

# Examples

#### Create a new Database using a specific type

You can specify the type using the `--type` option. This parameter defaults to `postgresql`, but you can use any of Aptible's [Supported Databases](/docs/core-concepts/managed-databases/supported-databases/overview).

For example, to create a [Redis](/docs/core-concepts/managed-databases/supported-databases/redis) database:

```shell theme={null}
aptible db:create --type redis
```

#### Create a new Database using a specific version

Use the `--version` flag in combination with `--type` to use a specific version:

```shell theme={null}
aptible db:create --type postgresql --version 9.6
```

> 📘 Use the [`aptible db:versions`](/docs/reference/aptible-cli/cli-commands/cli-db-versions) command to identify available versions.

#### Create a new Database with a custom Disk Size

```shell theme={null}
aptible db:create --disk-size 20 "$DB_HANDLE"
```

#### Create a new Database with a custom Container Size

```shell theme={null}
aptible db:create --container-size 2048 "$DB_HANDLE"
```

#### Container Sizes (MB)

**General Purpose(M)**: 512, 1024, 2048, 4096, 7168, 15360, 30720, 61440, 153600, 245760

#### Profiles

`m`: General Purpose (M) container \
`c`: CPU-Optimized (C) container \
`r`: Memory Optimized (R) container


# aptible db:deprovision
Source: https://www.aptible.com/docs/reference/aptible-cli/cli-commands/cli-db-deprovision



This command is used to deprovision a [Database](/docs/core-concepts/managed-databases/overview).

# Synopsis

```
Usage:
  aptible db:deprovision HANDLE

Options:
  --env, [--environment=ENVIRONMENT]
```


# aptible db:dump
Source: https://www.aptible.com/docs/reference/aptible-cli/cli-commands/cli-db-dump



This command dumps a remote [PostgreSQL Database](/docs/core-concepts/managed-databases/supported-databases/postgresql) to a file.\
\
Synopsis

```
Usage:
  aptible db:dump HANDLE [pg_dump options]

Options:
  --env, [--environment=ENVIRONMENT]
```

For additional pg\_dump options, please review the following [PostgreSQL documentation that outlines command-line options that control the content and format of the output.](https://www.postgresql.org/docs/current/app-pgdump.html).


# aptible db:execute
Source: https://www.aptible.com/docs/reference/aptible-cli/cli-commands/cli-db-execute



This command executes SQL against a [Database](/docs/core-concepts/managed-databases/managing-databases/overview).

# Synopsis

```
Usage:
  aptible db:execute HANDLE SQL_FILE [--on-error-stop]

Options:
  --env, [--environment=ENVIRONMENT]
  [--on-error-stop], [--no-on-error-stop]
```


# aptible db:list
Source: https://www.aptible.com/docs/reference/aptible-cli/cli-commands/cli-db-list



This command lists [Databases](/docs/core-concepts/managed-databases/overview) in an [Environment](/docs/core-concepts/architecture/environments).

# Synopsis

```
Usage:
  aptible db:list

Options:
  --env, [--environment=ENVIRONMENT]
```


# aptible db:modify
Source: https://www.aptible.com/docs/reference/aptible-cli/cli-commands/cli-db-modify



This command modifies existing [Databases](/docs/core-concepts/managed-databases/managing-databases/overview). Running this command does not cause downtime.

# Synopsis

```
Usage:
  aptible db:modify HANDLE [--iops IOPS] [--volume-type [gp2, gp3]]

Options:
  --env, [--environment=ENVIRONMENT]
  [--iops=N]
  [--volume-type=VOLUME_TYPE]

```

> 📘 The IOPS option only applies to GP3 volume.  If you currently have a GP2 volume and need more IOPS, simultaneously specify both the `--volume-type gp3` and `--iops NNNN` options.

> 📘 The maximum IOPS is dependent on disk size and container profile and size. Disk size must meet a minimum ratio of 1 GB disk size per 500 IOPS. Use the following table to understand what container profiles and sizes can be used to meet your IOPS needs. These guidelines may change over time as existing instance types are retired and new ones are introduced.

<table>
  <thead>
    <tr>
      <th>Max IOPS</th>
      <th>Minimum Disk Size</th>
      <th>General Purpose (M)</th>
      <th>CPU-Optimized (C)</th>
      <th>Memory Optimized (R)</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>18750</td>
      <td>38GB</td>
      <td>512MB – 60GB</td>
      <td>n/a</td>
      <td>4GB – 60GB</td>
    </tr>

    <tr>
      <td>20000</td>
      <td>40GB</td>
      <td>n/a</td>
      <td>2GB – 30GB</td>
      <td>n/a</td>
    </tr>

    <tr>
      <td>30000</td>
      <td>60GB</td>
      <td>n/a</td>
      <td>n/a</td>
      <td>150GB, 240GB</td>
    </tr>

    <tr>
      <td>40000</td>
      <td>80GB</td>
      <td>153GB</td>
      <td>60GB</td>
      <td>368GB</td>
    </tr>

    <tr>
      <td>60000</td>
      <td>120GB</td>
      <td>240GB</td>
      <td>n/a</td>
      <td>496GB</td>
    </tr>

    <tr>
      <td>80000</td>
      <td>160GB</td>
      <td>n/a</td>
      <td>150GB - 368GB</td>
      <td>752GB</td>
    </tr>
  </tbody>
</table>


# aptible db:reload
Source: https://www.aptible.com/docs/reference/aptible-cli/cli-commands/cli-db-reload



This command reloads a [Database](/docs/core-concepts/managed-databases/managing-databases/overview) by replacing the running Database [Container](/docs/core-concepts/architecture/containers/overview) with a new one.

<Tip> Reloading can be useful if your Database appears to be misbehaving.</Tip>

<Note> Using [`aptible db:reload`](/docs/reference/aptible-cli/cli-commands/cli-db-reload) is faster than [`aptible db:restart`](/docs/reference/aptible-cli/cli-commands/cli-db-restart), but it does not let you [resize](/docs/core-concepts/scaling/database-scaling) your Database. </Note>

# Synopsis

```
Usage:
  aptible db:reload HANDLE

Options:
  --env, [--environment=ENVIRONMENT]
```


# aptible db:rename
Source: https://www.aptible.com/docs/reference/aptible-cli/cli-commands/cli-db-rename



This command renames a [Database](/docs/core-concepts/managed-databases/managing-databases/overview) handle. For this change to take effect, the Database must be restarted. After restart, the new Database handle will appear in log and metric drains.\
\
Synopsis

```
Usage:
  aptible db:rename OLD_HANDLE NEW_HANDLE [--environment ENVIRONMENT_HANDLE]

Options:
  --env, [--environment=ENVIRONMENT]
```


# aptible db:replicate
Source: https://www.aptible.com/docs/reference/aptible-cli/cli-commands/cli-db-replicate



This command creates a [Database Replica](/docs/core-concepts/managed-databases/managing-databases/replication-clustering). All new Replicas are created with the General Purpose (M) Container Profile, which is the [default Container Profile.](/docs/core-concepts/scaling/container-profiles#default-container-profile)

# Synopsis

```
Usage:
  aptible db:replicate HANDLE REPLICA_HANDLE [--container-size SIZE_MB] [--container-profile PROFILE]  [--disk-size SIZE_GB] [--iops IOPS] [--logical --version VERSION] [--key-arn KEY_ARN]

Options:
  --env, [--environment=ENVIRONMENT]
  [--container-size=N]
  [--container-profile PROFILE]
                               # Default: m
  [--size=N]
  [--disk-size=N]
  [--logical], [--no-logical]
  [--version=VERSION]
  [--iops=IOPS]
  [--key-arn=KEY_ARN]
```

> 📘 The `--version` option is only supported for postgresql logical replicas.

# Examples

#### Create a replica with a custom Disk Size

```shell theme={null}
aptible db:replicate "$DB_HANDLE" "$REPLICA_HANDLE" \
            --disk-size 20
```

#### Create a replica with a custom Container Size

```shell theme={null}
aptible db:replicate "$DB_HANDLE" "$REPLICA_HANDLE" \
            --container-size 2048
```

#### Create a replica with a custom Container and Disk Size

```shell theme={null}
aptible db:replicate "$DB_HANDLE" "$REPLICA_HANDLE" \
            --container-size 2048 \
            --disk-size 20
```

#### Create an upgraded replica for logical replication

```shell theme={null}
aptible db:replicate "$DB_HANDLE" "$REPLICA_HANDLE" \
            --logical --version 12
```

#### Container Sizes (MB)

**General Purpose(M)**: 512, 1024, 2048, 4096, 7168, 15360, 30720, 61440, 153600, 245760

#### Profiles

`m`: General Purpose (M) container \
`c`: CPU-Optimized (C) container \
`r`: Memory Optimized (R) container

# How Logical Replication Works

[`aptible db:replicate --logical`](/docs/reference/aptible-cli/cli-commands/cli-db-replicate) should work in most cases. This section provides additional details details on how the CLI command works for debugging or if you'd like to know more about what the command does for you.

The CLI command uses the `pglogical` extension to set up logical replication between the existing Database and the new replica Database. At a high level, these are the steps the CLI command takes to setup logical replication for you:

1. Update `max_worker_processes` on the replica based on the number of [PostgreSQL databases](https://www.postgresql.org/docs/current/managing-databases.html) being replicated. `pglogical` uses several worker processes per database so it can easily exhaust the default `max_worker_processes` if replicating more than a couple of databases.
2. Recreate all roles (users) on the replica. `pglogical`'s copy of the source database structure includes assigning the same owner to each table and granting the same permissions. The roles must exist on the replica in order for this to work.
3. For each PostgreSQL database on the source Database, excluding those that beginning with `template`:
   1. Create the database on the replica with the `aptible` user as the owner.
   2. Enable the `pglogical` extension on the source and replica database.
   3. Create a `pglogical` subscription between the source and replica database. This will copy the source database's structure (e.g. schemas, tables, permissions, extensions, etc.).
   4. Start the initial data sync. This will truncate and sync data for all tables in all schemas except for the `information_schema`, `pglogical`, and `pglogical_origin` schemas and schemas that begin with `pg_` (system schemas).

The replica does not wait for the initial data sync to complete before coming online. The time it takes to sync all of the data from the source Database depends on the size of the Database.

When run on the replica, the following query will list all tables that are not in the `replicating` state and, therefore, have not finished syncing the initial data from the source Database.

```postgresql theme={null}
SELECT * FROM pglogical.local_sync_status WHERE NOT sync_status = 'r';
```


# aptible db:restart
Source: https://www.aptible.com/docs/reference/aptible-cli/cli-commands/cli-db-restart



This command restarts a [Database](/docs/core-concepts/managed-databases/overview) and can be used to resize a Database.

<Tip> If you want to restart your Database in place without resizing it, consider using [`aptible db:reload`](/docs/reference/aptible-cli/cli-commands/cli-db-reload) instead. [`aptible db:reload`](/docs/reference/aptible-cli/cli-commands/cli-db-reload) is slightly faster than [`aptible db:restart`](/docs/reference/aptible-cli/cli-commands/cli-db-restart).</Tip>

# Synopsis

```
Usage:
  aptible db:restart HANDLE [--container-size SIZE_MB] [--container-profile PROFILE]  [--disk-size SIZE_GB] [--iops IOPS] [--volume-type [gp2, gp3]]

Options:
  --env, [--environment=ENVIRONMENT]
  [--container-size=N]
  [--container-profile PROFILE]
                               # Default: m
  [--disk-size=N]
  [--size=N]
  [--iops=N]
  [--volume-type=VOLUME_TYPE]
```

# Examples

#### Resize the Container

```shell theme={null}
aptible db:restart "$DB_HANDLE" \
        --container-size 2048
```

#### Resize the Disk

```shell theme={null}
aptible db:restart "$DB_HANDLE" \
        --disk-size 120
```

#### Resize Container and Disk

```shell theme={null}
aptible db:restart "$DB_HANDLE" \
        --container-size 2048 \
        --disk-size 120
```

#### Container Sizes (MB)

**All container profiles** support the following sizes: 512, 1024, 2048, 4096, 7168, 15360, 30720

The following profiles offer additional supported sizes:

* **General Purpose (M) - Legacy, General Purpose(M) and Memory Optimized(R)** - **Legacy**: 61440, 153600, 245760
* **CPU-Optimized (C)**: 61440, 153600, 245760, 376832
* **Memory Optimized (R)**: 61440, 153600, 245760, 376832, 507904, 770048

#### Profiles

`m`: General purpose container \
`c`: CPU-optimized container \
`r`: Memory optimized container


# aptible db:tunnel
Source: https://www.aptible.com/docs/reference/aptible-cli/cli-commands/cli-db-tunnel



This command creates [Database Tunnels](/docs/core-concepts/managed-databases/connecting-databases/database-tunnels). If your [Database](/docs/core-concepts/managed-databases/overview) exposes multiple [Database Credentials](/docs/core-concepts/managed-databases/connecting-databases/database-credentials), you can specify which one you'd like to tunnel to.

## Synopsis

```
Usage:
  aptible db:tunnel HANDLE

Options:
  --env, [--environment=ENVIRONMENT]
  [--port=N]
  [--type=TYPE]
```

# Examples

To tunnel using your Database's default Database Credential:

```shell theme={null}
aptible db:tunnel "$DB_HANDLE"
```

To tunnel using a specific Database Credential:

```shell theme={null}
aptible db:tunnel "$DB_HANDLE" --type "$CREDENTIAL_TYPE"
```


# aptible db:url
Source: https://www.aptible.com/docs/reference/aptible-cli/cli-commands/cli-db-url



This command prints [Database Credentials](/docs/core-concepts/managed-databases/connecting-databases/database-credentials) (which are displayed as Database URLs).

# Synopsis

```
Usage:
  aptible db:url HANDLE

Options:
  --env, [--environment=ENVIRONMENT]
  [--type=TYPE]
```


# aptible db:versions
Source: https://www.aptible.com/docs/reference/aptible-cli/cli-commands/cli-db-versions



This command lists all available [Database](/docs/core-concepts/managed-databases/managing-databases/overview) versions.\
\
This is useful for identifying available versions when creating a new Database.

# Synopsis

```
Usage:
  aptible db:versions
```


# aptible deploy
Source: https://www.aptible.com/docs/reference/aptible-cli/cli-commands/cli-deploy



This command is used to deploy an App. This can be used for [deploying via Docker image](/docs/how-to-guides/app-guides/migrate-dockerfile-to-direct-image-deploy) and/or for [Synchronizing Configuration and code changes](/docs/how-to-guides/app-guides/synchronize-config-code-changes).

Docker image names are only supported in image:tag; sha256 format is not supported.

# Synopsis

```
Usage:
  aptible deploy [--app APP] [OPTIONS] [VAR1=VAL1] [VAR2=VAL2] [...]

Options:
      [--git-commitish=GIT_COMMITISH]                                  # Deploy a specific git commit or branch: the commitish must have been pushed to Aptible beforehand
      [--git-detach], [--no-git-detach]                                # Detach this app from its git repository: its Procfile, Dockerfile, and .aptible.yml will be ignored until you deploy again with git
      [--docker-image=DOCKER_IMAGE]                                    # The docker image to deploy. If none specified, the currently deployed image will be pulled again
      [--private-registry-username=USERNAME]                           # Username for Docker images located in a private repository
      [--private-registry-password=PASSWORD]                           # Password for Docker images located in a private repository
      [--private-registry-email=EMAIL]                                 # This parameter is deprecated
      [--app=APP]
  --env, [--environment=ENVIRONMENT]
  -r, [--remote=REMOTE]
```


# aptible endpoints:database:create
Source: https://www.aptible.com/docs/reference/aptible-cli/cli-commands/cli-endpoints-database-create



This command creates a [Database Endpoint.](/docs/core-concepts/managed-databases/connecting-databases/database-endpoints)

# Synopsis

```
Usage:
  aptible endpoints:database:create DATABASE

Options:
  --env, [--environment=ENVIRONMENT]
  [--internal], [--no-internal]   # Restrict this Endpoint to internal traffic
  [--ip-whitelist=one two three]  # A list of IPv4 sources (addresses or CIDRs) to which to restrict traffic to this Endpoint
```

# Examples

#### Create a new Database Endpoint

```shell theme={null}
aptible endpoints:database:create  "$DATABASE_HANDLE"
```

#### Create a new Database Endpoint with IP Filtering

```shell theme={null}
aptible endpoints:database:create  "$DATABASE_HANDLE" \
        --ip-whitelist 1.1.1.1/1 2.2.2.2
```


# aptible endpoints:database:modify
Source: https://www.aptible.com/docs/reference/aptible-cli/cli-commands/cli-endpoints-database-modify



This command modifies an existing [Database Endpoint.](/docs/core-concepts/managed-databases/connecting-databases/database-endpoints)

# Synopsis

```
Usage:
  aptible endpoints:database:modify --database DATABASE ENDPOINT_HOSTNAME

Options:
  --env, [--environment=ENVIRONMENT]
  [--database=DATABASE]
  [--ip-whitelist=one two three]  # A list of IPv4 sources (addresses or CIDRs) to which to restrict traffic to this Endpoint
  [--no-ip-whitelist]             # Disable IP Whitelist
```


# aptible endpoints:deprovision
Source: https://www.aptible.com/docs/reference/aptible-cli/cli-commands/cli-endpoints-deprovision



This command deprovisions an [App Endpoint](/docs/core-concepts/apps/connecting-to-apps/app-endpoints/overview) or a [Database Endpoint](/docs/core-concepts/managed-databases/connecting-databases/database-endpoints).

# Synopsis

```
Usage:
  aptible endpoints:deprovision [--app APP | --database DATABASE] ENDPOINT_HOSTNAME

Options:
      [--app=APP]
  --env, [--environment=ENVIRONMENT]
  -r, [--remote=REMOTE]
      [--database=DATABASE]
```

# Examples

The examples below `$ENDPOINT_HOSTNAME` reference the [Endpoint Hostname](/docs/core-concepts/apps/connecting-to-apps/app-endpoints/custom-domain#endpoint-hostname) for the Endpoint you'd like to deprovision.

> 📘 Use the [`aptible endpoints:list`](/docs/reference/aptible-cli/cli-commands/cli-endpoints-list) command to easily locate the [Endpoint Hostname](/docs/core-concepts/apps/connecting-to-apps/app-endpoints/custom-domain#endpoint-hostname) for a given Endpoint.

#### Deprovision an App Endpoint

```shell theme={null}
aptible endpoints:deprovision \
        --app "$APP_HANDLE" \
        "$ENDPOINT_HOSTNAME"
```

#### Deprovision a Database Endpoint

```shell theme={null}
aptible endpoints:deprovision \
        --database "$DATABASE_HANDLE" \
        "$ENDPOINT_HOSTNAME"
```


# aptible endpoints:grpc:create
Source: https://www.aptible.com/docs/reference/aptible-cli/cli-commands/cli-endpoints-grpc-create



This command creates a new [gRPC Endpoint](/docs/core-concepts/apps/connecting-to-apps/app-endpoints/grpc-endpoints).

# Synopsis

```
Usage:
  aptible endpoints:grpc:create [--app APP] SERVICE

Options:
  --env, [--environment=ENVIRONMENT]
      [--app=APP]
  -r, [--remote=REMOTE]
      [--default-domain], [--no-default-domain]                          # Enable Default Domain on this Endpoint
      [--port=N]                                                         # A port to expose on this Endpoint
      [--idle-timeout=IDLE_TIMEOUT]                                      # Timeout (seconds) to enforce idle timeouts while sending and receiving responses. Use "default" to reset to the platform default
      [--internal], [--no-internal]                                      # Restrict this Endpoint to internal traffic
      [--ip-whitelist=one two three]                                     # A list of IPv4 sources (addresses or CIDRs) to which to restrict traffic to this Endpoint
      [--certificate-file=CERTIFICATE_FILE]                              # A file containing a certificate to use on this Endpoint
      [--private-key-file=PRIVATE_KEY_FILE]                              # A file containing a private key to use on this Endpoint
      [--managed-tls], [--no-managed-tls]                                # Enable Managed TLS on this Endpoint
      [--managed-tls-domain=MANAGED_TLS_DOMAIN]                          # A domain to use for Managed TLS
      [--certificate-fingerprint=CERTIFICATE_FINGERPRINT]                # The fingerprint of an existing Certificate to use on this Endpoint
      [--ssl-protocols-override=SSL_PROTOCOLS_OVERRIDE]                  # Specify the allowed SSL protocols. Valid options: "TLSv1 TLSv1.1 TLSv1.2", "TLSv1.1 TLSv1.2", "TLSv1.2", "TLSv1.3". Use "default" to reset to the platform default
      [--ssl-ciphers-override=SSL_CIPHERS_OVERRIDE]                      # Specify the allowed SSL ciphers. Use "default" to reset to the platform default
      [--disable-weak-cipher-suites], [--no-disable-weak-cipher-suites]  # Block the SSLv3 protocol and RC4 ciphers
```

# Examples

In all the examples below, `$SERVICE` represents the name of a [Service](/docs/core-concepts/apps/deploying-apps/services) for the app you add an Endpoint to.

> 📘 If your app is using an [Implicit Service](/docs/how-to-guides/app-guides/define-services#implicit-service-cmd), the service name is always `cmd`.

#### Create a new Endpoint using custom Container Ports and an existing [Custom Certificate](/docs/core-concepts/apps/connecting-to-apps/app-endpoints/custom-certificate)

In the example below, `$CERTIFICATE_FINGERPRINT` is the SHA-256 fingerprint of a [Custom Certificate](/docs/core-concepts/apps/connecting-to-apps/app-endpoints/custom-certificate) that exist in the same [Environment](/docs/core-concepts/architecture/environments) as the App you are adding an Endpoint for.

> 📘 Tip: Use the Dashboard to easily locate the Certificate Fingerprint for a given Certificate.

> ❗️ Warning: Everything after the `--ports` argument is assumed to be part of the list of ports, so you need to pass it last.

```shell theme={null}
aptible endpoints:grpc:create \
        "$SERVICE" \
        --app "$APP_HANDLE" \
        --certificate-fingerprint "$CERTIFICATE_FINGERPRINT" \
        --ports 8000 8001 8002 8003
```

#### More Examples

This command is fairly similar in usage to [`aptible endpoints:https:create`](/docs/reference/aptible-cli/cli-commands/cli-endpoints-https-create). Review the examples there.


# aptible endpoints:grpc:modify
Source: https://www.aptible.com/docs/reference/aptible-cli/cli-commands/cli-endpoints-grpc-modify



This command lets you modify [gRPC Endpoints](/docs/core-concepts/apps/connecting-to-apps/app-endpoints/grpc-endpoints).

# Synopsis

```
Usage:
  aptible endpoints:grpc:modify [--app APP] ENDPOINT_HOSTNAME

Options:
  --env, [--environment=ENVIRONMENT]
      [--app=APP]
  -r, [--remote=REMOTE]
      [--port=N]                                                         # A port to expose on this Endpoint
      [--idle-timeout=IDLE_TIMEOUT]                                      # Timeout (seconds) to enforce idle timeouts while sending and receiving responses. Use "default" to reset to the platform default
      [--ip-whitelist=one two three]                                     # A list of IPv4 sources (addresses or CIDRs) to which to restrict traffic to this Endpoint
      [--no-ip-whitelist]                                                # Disable IP Whitelist
      [--certificate-file=CERTIFICATE_FILE]                              # A file containing a certificate to use on this Endpoint
      [--private-key-file=PRIVATE_KEY_FILE]                              # A file containing a private key to use on this Endpoint
      [--managed-tls], [--no-managed-tls]                                # Enable Managed TLS on this Endpoint
      [--managed-tls-domain=MANAGED_TLS_DOMAIN]                          # A domain to use for Managed TLS
      [--certificate-fingerprint=CERTIFICATE_FINGERPRINT]                # The fingerprint of an existing Certificate to use on this Endpoint
      [--ssl-protocols-override=SSL_PROTOCOLS_OVERRIDE]                  # Specify the allowed SSL protocols. Valid options: "TLSv1 TLSv1.1 TLSv1.2", "TLSv1.1 TLSv1.2", "TLSv1.2", "TLSv1.3". Use "default" to reset to the platform default
      [--ssl-ciphers-override=SSL_CIPHERS_OVERRIDE]                      # Specify the allowed SSL ciphers. Use "default" to reset to the platform default
      [--disable-weak-cipher-suites], [--no-disable-weak-cipher-suites]  # Block the SSLv3 protocol and RC4 ciphers
```

# Examples

The options available for this command are similar to those available for [`aptible endpoints:grpc:create`](/docs/reference/aptible-cli/cli-commands/cli-endpoints-grpc-create). Review the examples there.


# aptible endpoints:https:create
Source: https://www.aptible.com/docs/reference/aptible-cli/cli-commands/cli-endpoints-https-create



This command created a new [HTTPS Endpoint](/docs/core-concepts/apps/connecting-to-apps/app-endpoints/https-endpoints/overview).

# Synopsis

```
Usage:
  aptible endpoints:https:create [--app APP] SERVICE

Options:
  --env, [--environment=ENVIRONMENT]
      [--app=APP]
  -r, [--remote=REMOTE]
      [--default-domain], [--no-default-domain]                        # Enable Default Domain on this Endpoint
      [--port=N]                                                       # A port to expose on this Endpoint
      [--idle-timeout=IDLE_TIMEOUT]                                    # Timeout (seconds) to enforce idle timeouts while sending and receiving responses. Use "default" to reset to the platform default
      [--load-balancing-algorithm-type=LOAD_BALANCING_ALGORITHM_TYPE]  # The load balancing algorithm for this Endpoint. Valid options are round_robin, least_outstanding_requests, and weighted_random
      [--shared], [--no-shared]                                        # Share this Endpoint's load balancer with other Endpoints
      [--force-ssl], [--no-force-ssl]                                  # Redirect all HTTP requests to HTTPS, and enable the Strict-Transport-Security header (HSTS)
      [--maintenance-page-url=MAINTENANCE_PAGE_URL]                    # The URL of a maintenance page to cache and serve when requests time out, or your app is unhealthy. Use "default" to reset to the platform default
      [--release-healthcheck-timeout=RELEASE_HEALTHCHECK_TIMEOUT]      # Timeout (seconds) to wait for your app to respond to a release health check. Use "default" to reset to the platform default
      [--show-elb-healthchecks], [--no-show-elb-healthchecks]          # Show all runtime health check requets in the endpoint's logs
      [--ssl-protocols-override=SSL_PROTOCOLS_OVERRIDE]                # Specify the allowed SSL protocols. Valid options: "TLSv1 TLSv1.1 TLSv1.2", "TLSv1 TLSv1.1 TLSv1.2 PFS", "TLSv1.1 TLSv1.2", "TLSv1.1 TLSv1.2 PFS", "TLSv1.2", "TLSv1.2 PFS", "TLSv1.2 PFS TLSv1.3", "TLSv1.3". PFS options require an HTTPS (ALB) endpoint. Use "default" to reset to the platform default
      [--strict-health-checks], [--no-strict-health-checks]            # Require containers to respond to health checks with a 200 OK HTTP response.
      [--internal], [--no-internal]                                    # Restrict this Endpoint to internal traffic
      [--ip-whitelist=one two three]                                   # A list of IPv4 sources (addresses or CIDRs) to which to restrict traffic to this Endpoint
      [--certificate-file=CERTIFICATE_FILE]                            # A file containing a certificate to use on this Endpoint
      [--private-key-file=PRIVATE_KEY_FILE]                            # A file containing a private key to use on this Endpoint
      [--managed-tls], [--no-managed-tls]                              # Enable Managed TLS on this Endpoint
      [--managed-tls-domain=MANAGED_TLS_DOMAIN]                        # A domain to use for Managed TLS
      [--certificate-fingerprint=CERTIFICATE_FINGERPRINT]              # The fingerprint of an existing Certificate to use on this Endpoint
```

# Examples

In all the examples below, `$SERVICE` represents the name of a [Service](/docs/core-concepts/apps/deploying-apps/services) for the app you are adding an Endpoint to.

> 📘 If your app is using an [Implicit Service](/docs/how-to-guides/app-guides/define-services#implicit-service-cmd), the service name is always `cmd`.

#### Create a new Endpoint using a new [Custom Certificate](/docs/core-concepts/apps/connecting-to-apps/app-endpoints/custom-certificate)

In the example below, `$CERTIFICATE_FILE` is the path to a file containing a PEM-formatted certificate bundle, and `$PRIVATE_KEY_FILE` is the path to a file containing the matching private key (see [Format](/docs/core-concepts/apps/connecting-to-apps/app-endpoints/custom-certificate#format) for more information).

```shell theme={null}
aptible endpoints:https:create \
        --app "$APP_HANDLE" \
        --certificate-file "$CERTIFICATE_FILE" \
        --private-key-file "$PRIVATE_KEY_FILE" \
        "$SERVICE"
```

#### Create a new Endpoint using an existing [Custom Certificate](/docs/core-concepts/apps/connecting-to-apps/app-endpoints/custom-certificate)

In the example below, `$CERTIFICATE_FINGERPRINT` is the SHA-256 fingerprint of a [Custom Certificate](/docs/core-concepts/apps/connecting-to-apps/app-endpoints/custom-certificate) that exist in the same [Environment](/docs/core-concepts/architecture/environments) as the App you are adding an Endpoint for.

> 📘 Tip: Use the Dashboard to easily locate the Certificate Fingerprint for a given Certificate.

```shell theme={null}
aptible endpoints:https:create \
        --app "$APP_HANDLE" \
        --certificate-fingerprint "$CERTIFICATE_FINGERPRINT" \
        "$SERVICE"
```

#### Create a new Endpoint using [Managed TLS](/docs/core-concepts/apps/connecting-to-apps/app-endpoints/managed-tls)

In the example below, `$YOUR_DOMAIN` is the domain you intend to use with your Endpoint.

After initial provisioning completes, the CLI will return the [Managed HTTPS Validation Records](/docs/core-concepts/apps/connecting-to-apps/app-endpoints/managed-tls#managed-https-validation-records) you need to create in order to finalize the Endpoint.

Once you've created these records, use the [`aptible endpoints:renew`](/docs/reference/aptible-cli/cli-commands/cli-endpoints-renew) to complete provisioning.

```shell theme={null}
aptible endpoints:https:create \
        --app "$APP_HANDLE" \
        --managed-tls \
        --managed-tls-domain "$YOUR_DOMAIN"
        "$SERVICE"
```

#### Create a new Endpoint using a [Default Domain](/docs/core-concepts/apps/connecting-to-apps/app-endpoints/default-domain)

```shell theme={null}
aptible endpoints:https:create \
        --app "$APP_HANDLE" \
        --default-domain \
        "$SERVICE"
```

#### Create a new Endpoint using a custom Container Port and an existing Certificate

```shell theme={null}
aptible endpoints:https:create \
        --app "$APP_HANDLE" \
        --certificate-fingerprint "$CERTIFICATE_FINGERPRINT" \
        --port 80 \
        "$SERVICE"
```


# aptible endpoints:https:modify
Source: https://www.aptible.com/docs/reference/aptible-cli/cli-commands/cli-endpoints-https-modify



This command modifies an existing App [HTTP(S) Endpoint.](/docs/core-concepts/apps/connecting-to-apps/app-endpoints/https-endpoints/overview)

> 📘 Tip: Use the [`aptible endpoints:list`](/docs/reference/aptible-cli/cli-commands/cli-endpoints-list) command to easily locate the [Endpoint Hostname](/docs/core-concepts/apps/connecting-to-apps/app-endpoints/custom-domain#endpoint-hostname) for a given Endpoint.

# Synopsis

```
Usage:
  aptible endpoints:https:modify [--app APP] ENDPOINT_HOSTNAME

Options:
  --env, [--environment=ENVIRONMENT]
      [--app=APP]
  -r, [--remote=REMOTE]
      [--port=N]                                                       # A port to expose on this Endpoint
      [--idle-timeout=IDLE_TIMEOUT]                                    # Timeout (seconds) to enforce idle timeouts while sending and receiving responses. Use "default" to reset to the platform default
      [--load-balancing-algorithm-type=LOAD_BALANCING_ALGORITHM_TYPE]  # The load balancing algorithm for this Endpoint. Valid options are round_robin, least_outstanding_requests, and weighted_random
      [--shared], [--no-shared]                                        # Share this Endpoint's load balancer with other Endpoints
      [--force-ssl], [--no-force-ssl]                                  # Redirect all HTTP requests to HTTPS, and enable the Strict-Transport-Security header (HSTS)
      [--maintenance-page-url=MAINTENANCE_PAGE_URL]                    # The URL of a maintenance page to cache and serve when requests time out, or your app is unhealthy. Use "default" to reset to the platform default
      [--release-healthcheck-timeout=RELEASE_HEALTHCHECK_TIMEOUT]      # Timeout (seconds) to wait for your app to respond to a release health check. Use "default" to reset to the platform default
      [--show-elb-healthchecks], [--no-show-elb-healthchecks]          # Show all runtime health check requets in the endpoint's logs
      [--ssl-protocols-override=SSL_PROTOCOLS_OVERRIDE]                # Specify the allowed SSL protocols. Valid options: "TLSv1 TLSv1.1 TLSv1.2", "TLSv1 TLSv1.1 TLSv1.2 PFS", "TLSv1.1 TLSv1.2", "TLSv1.1 TLSv1.2 PFS", "TLSv1.2", "TLSv1.2 PFS", "TLSv1.2 PFS TLSv1.3", "TLSv1.3". PFS options require an HTTPS (ALB) endpoint. Use "default" to reset to the platform default
      [--strict-health-checks], [--no-strict-health-checks]            # Require containers to respond to health checks with a 200 OK HTTP response.
      [--ip-whitelist=one two three]                                   # A list of IPv4 sources (addresses or CIDRs) to which to restrict traffic to this Endpoint
      [--no-ip-whitelist]                                              # Disable IP Whitelist
      [--certificate-file=CERTIFICATE_FILE]                            # A file containing a certificate to use on this Endpoint
      [--private-key-file=PRIVATE_KEY_FILE]                            # A file containing a private key to use on this Endpoint
      [--managed-tls], [--no-managed-tls]                              # Enable Managed TLS on this Endpoint
      [--managed-tls-domain=MANAGED_TLS_DOMAIN]                        # A domain to use for Managed TLS
      [--certificate-fingerprint=CERTIFICATE_FINGERPRINT]              # The fingerprint of an existing Certificate to use on this Endpoint
```

# Examples

The options available for this command are similar to those available for [`aptible endpoints:https:create`](/docs/reference/aptible-cli/cli-commands/cli-endpoints-https-create). Review the examples there.


# aptible endpoints:list
Source: https://www.aptible.com/docs/reference/aptible-cli/cli-commands/cli-endpoints-list



This command lists the Endpoints for an [App](/docs/core-concepts/apps/overview) or [Database](/docs/core-concepts/managed-databases/overview).

# Synopsis

```
Usage:
  aptible endpoints:list [--app APP | --database DATABASE]

Options:
      [--app=APP]
  --env, [--environment=ENVIRONMENT]
  -r, [--remote=REMOTE]
      [--database=DATABASE]
```

# Examples

#### List Endpoints for an App

```shell theme={null}
aptible endpoints:list \
        --app "$APP_HANDLE"
```

#### List Endpoints for a Database

```shell theme={null}
aptible endpoints:list \
        --database "$DATABASE_HANDLE"
```

#### Sample Output

```
Service: cmd
Hostname: elb-foobar-123.aptible.in
Status: provisioned
Type: https
Port: default
Load Balancing Algorithm Type: round_robin
Shared: false
Internal: false
IP Whitelist: all traffic
Default Domain Enabled: false
Managed TLS Enabled: true
Managed TLS Domain: app.example.com
Managed TLS DNS Challenge Hostname: acme.elb-foobar-123.aptible.in
Managed TLS Status: ready
```

> 📘 The above block is repeated for each matching Endpoint.


# aptible endpoints:renew
Source: https://www.aptible.com/docs/reference/aptible-cli/cli-commands/cli-endpoints-renew



This command triggers an initial renewal of a [Managed TLS](/docs/core-concepts/apps/connecting-to-apps/app-endpoints/managed-tls) Endpoint after creating it using [`aptible endpoints:https:create`](/docs/reference/aptible-cli/cli-commands/cli-endpoints-https-create) or [`aptible endpoints:tls:create`](/docs/reference/aptible-cli/cli-commands/cli-endpoints-tls-create) and having set up the required [Managed HTTPS Validation Records](/docs/core-concepts/apps/connecting-to-apps/app-endpoints/managed-tls#managed-https-validation-records).

> ⚠️ We recommend reviewing the documentation on [rate limits](/docs/core-concepts/apps/connecting-to-apps/app-endpoints/managed-tls#rate-limits) before using this command automatically.\
> \
> 📘 You only need to do this once! After initial provisioning, Aptible automatically renews your Managed TLS certificates on a periodic basis.

# Synopsis

> 📘  Use the [`aptible endpoints:list`](/docs/reference/aptible-cli/cli-commands/cli-endpoints-list) command to easily locate the [Endpoint Hostname](/docs/core-concepts/apps/connecting-to-apps/app-endpoints/custom-domain#endpoint-hostname) for a given Endpoint.

```
Usage:
  aptible endpoints:renew [--app APP] ENDPOINT_HOSTNAME

Options:
      [--app=APP]
  --env, [--environment=ENVIRONMENT]
  -r, [--remote=REMOTE]
```


# aptible endpoints:tcp:create
Source: https://www.aptible.com/docs/reference/aptible-cli/cli-commands/cli-endpoints-tcp-create



This command creates a new App [TCP Endpoint](/docs/core-concepts/apps/connecting-to-apps/app-endpoints/tcp-endpoints).

# Synopsis

```
Usage:
  aptible endpoints:tcp:create [--app APP] SERVICE

Options:
  --env, [--environment=ENVIRONMENT]
      [--app=APP]
  -r, [--remote=REMOTE]
      [--default-domain], [--no-default-domain]  # Enable Default Domain on this Endpoint
      [--ports=one two three]                    # A list of ports to expose on this Endpoint
      [--idle-timeout=IDLE_TIMEOUT]              # Timeout (seconds) to enforce idle timeouts while sending and receiving responses. Use "default" to reset to the platform default
      [--internal], [--no-internal]              # Restrict this Endpoint to internal traffic
      [--ip-whitelist=one two three]             # A list of IPv4 sources (addresses or CIDRs) to which to restrict traffic to this Endpoint
```

# Examples

In all the examples below, `$SERVICE` represents the name of a [Service](/docs/core-concepts/apps/deploying-apps/services) for the Spp you are adding an Endpoint to.

> 📘 If your app is using an [Implicit Service](/docs/how-to-guides/app-guides/define-services#implicit-service-cmd), the service name is always `cmd`.

#### Create a new Endpoint

```shell theme={null}
aptible endpoints:tcp:create \
        --app "$APP_HANDLE" \
        "$SERVICE"
```

#### Create a new Endpoint using a [Default Domain](/docs/core-concepts/apps/connecting-to-apps/app-endpoints/default-domain)

```shell theme={null}
aptible endpoints:tcp:create \
        --app "$APP_HANDLE" \
        --default-domain \
        "$SERVICE"
```

#### Create a new Endpoint using a custom set of Container Ports

> ❗️ Warning

> The `--ports` argument accepts a list of ports, so you need to pass it last.

```shell theme={null}
aptible endpoints:tcp:create \
        --app "$APP_HANDLE" \
        "$SERVICE" \
        --ports 8000 8001 8002 8003
```


# aptible endpoints:tcp:modify
Source: https://www.aptible.com/docs/reference/aptible-cli/cli-commands/cli-endpoints-tcp-modify



This command modifies App [TCP Endpoints](/docs/core-concepts/apps/connecting-to-apps/app-endpoints/tcp-endpoints).

# Synopsis

```
Usage:
  aptible endpoints:tcp:modify [--app APP] ENDPOINT_HOSTNAME

Options:
  --env, [--environment=ENVIRONMENT]
      [--app=APP]
  -r, [--remote=REMOTE]
      [--ports=one two three]         # A list of ports to expose on this Endpoint
      [--idle-timeout=IDLE_TIMEOUT]   # Timeout (seconds) to enforce idle timeouts while sending and receiving responses. Use "default" to reset to the platform default
      [--ip-whitelist=one two three]  # A list of IPv4 sources (addresses or CIDRs) to which to restrict traffic to this Endpoint
      [--no-ip-whitelist]             # Disable IP Whitelist
```

# Examples

The options available for this command are similar to those available for [`aptible endpoints:tcp:create`](/docs/reference/aptible-cli/cli-commands/cli-endpoints-tcp-create). Review the examples there.


# aptible endpoints:tls:create
Source: https://www.aptible.com/docs/reference/aptible-cli/cli-commands/cli-endpoints-tls-create



This command creates a new [TLS Endpoint](/docs/core-concepts/apps/connecting-to-apps/app-endpoints/tls-endpoints).

# Synopsis

```
Usage:
  aptible endpoints:tls:create [--app APP] SERVICE

Options:
  --env, [--environment=ENVIRONMENT]
      [--app=APP]
  -r, [--remote=REMOTE]
      [--default-domain], [--no-default-domain]                          # Enable Default Domain on this Endpoint
      [--ports=one two three]                                            # A list of ports to expose on this Endpoint
      [--idle-timeout=IDLE_TIMEOUT]                                      # Timeout (seconds) to enforce idle timeouts while sending and receiving responses. Use "default" to reset to the platform default
      [--internal], [--no-internal]                                      # Restrict this Endpoint to internal traffic
      [--ip-whitelist=one two three]                                     # A list of IPv4 sources (addresses or CIDRs) to which to restrict traffic to this Endpoint
      [--certificate-file=CERTIFICATE_FILE]                              # A file containing a certificate to use on this Endpoint
      [--private-key-file=PRIVATE_KEY_FILE]                              # A file containing a private key to use on this Endpoint
      [--managed-tls], [--no-managed-tls]                                # Enable Managed TLS on this Endpoint
      [--managed-tls-domain=MANAGED_TLS_DOMAIN]                          # A domain to use for Managed TLS
      [--certificate-fingerprint=CERTIFICATE_FINGERPRINT]                # The fingerprint of an existing Certificate to use on this Endpoint
      [--ssl-protocols-override=SSL_PROTOCOLS_OVERRIDE]                  # Specify the allowed SSL protocols. Valid options: "TLSv1 TLSv1.1 TLSv1.2", "TLSv1.1 TLSv1.2", "TLSv1.2", "TLSv1.3". Use "default" to reset to the platform default
      [--ssl-ciphers-override=SSL_CIPHERS_OVERRIDE]                      # Specify the allowed SSL ciphers. Use "default" to reset to the platform default
      [--disable-weak-cipher-suites], [--no-disable-weak-cipher-suites]  # Block the SSLv3 protocol and RC4 ciphers
```

# Examples

In all the examples below, `$SERVICE` represents the name of a [Service](/docs/core-concepts/apps/deploying-apps/services) for the app you add an Endpoint to.

> 📘 If your app is using an [Implicit Service](/docs/how-to-guides/app-guides/define-services#implicit-service-cmd), the service name is always `cmd`.

#### Create a new Endpoint using custom Container Ports and an existing [Custom Certificate](/docs/core-concepts/apps/connecting-to-apps/app-endpoints/custom-certificate)

In the example below, `$CERTIFICATE_FINGERPRINT` is the SHA-256 fingerprint of a [Custom Certificate](/docs/core-concepts/apps/connecting-to-apps/app-endpoints/custom-certificate) that exist in the same [Environment](/docs/core-concepts/architecture/environments) as the App you are adding an Endpoint for.

> 📘 Tip: Use the Dashboard to easily locate the Certificate Fingerprint for a given Certificate.

> ❗️ Warning: Everything after the `--ports` argument is assumed to be part of the list of ports, so you need to pass it last.

```shell theme={null}
aptible endpoints:tls:create \
        "$SERVICE" \
        --app "$APP_HANDLE" \
        --certificate-fingerprint "$CERTIFICATE_FINGERPRINT" \
        --ports 8000 8001 8002 8003
```

#### More Examples

This command is fairly similar in usage to [`aptible endpoints:https:create`](/docs/reference/aptible-cli/cli-commands/cli-endpoints-https-create). Review the examples there.


# aptible endpoints:tls:modify
Source: https://www.aptible.com/docs/reference/aptible-cli/cli-commands/cli-endpoints-tls-modify



This command lets you modify [TLS Endpoints](/docs/core-concepts/apps/connecting-to-apps/app-endpoints/tls-endpoints).

# Synopsis

```
Usage:
  aptible endpoints:tls:modify [--app APP] ENDPOINT_HOSTNAME

Options:
  --env, [--environment=ENVIRONMENT]
      [--app=APP]
  -r, [--remote=REMOTE]
      [--ports=one two three]                                            # A list of ports to expose on this Endpoint
      [--idle-timeout=IDLE_TIMEOUT]                                      # Timeout (seconds) to enforce idle timeouts while sending and receiving responses. Use "default" to reset to the platform default
      [--ip-whitelist=one two three]                                     # A list of IPv4 sources (addresses or CIDRs) to which to restrict traffic to this Endpoint
      [--no-ip-whitelist]                                                # Disable IP Whitelist
      [--certificate-file=CERTIFICATE_FILE]                              # A file containing a certificate to use on this Endpoint
      [--private-key-file=PRIVATE_KEY_FILE]                              # A file containing a private key to use on this Endpoint
      [--managed-tls], [--no-managed-tls]                                # Enable Managed TLS on this Endpoint
      [--managed-tls-domain=MANAGED_TLS_DOMAIN]                          # A domain to use for Managed TLS
      [--certificate-fingerprint=CERTIFICATE_FINGERPRINT]                # The fingerprint of an existing Certificate to use on this Endpoint
      [--ssl-protocols-override=SSL_PROTOCOLS_OVERRIDE]                  # Specify the allowed SSL protocols. Valid options: "TLSv1 TLSv1.1 TLSv1.2", "TLSv1.1 TLSv1.2", "TLSv1.2", "TLSv1.3". Use "default" to reset to the platform default
      [--ssl-ciphers-override=SSL_CIPHERS_OVERRIDE]                      # Specify the allowed SSL ciphers. Use "default" to reset to the platform default
      [--disable-weak-cipher-suites], [--no-disable-weak-cipher-suites]  # Block the SSLv3 protocol and RC4 ciphers
```

# Examples

The options available for this command are similar to those available for [`aptible endpoints:tls:create`](/docs/reference/aptible-cli/cli-commands/cli-endpoints-tls-create). Review the examples there.


# aptible environment:ca_cert
Source: https://www.aptible.com/docs/reference/aptible-cli/cli-commands/cli-environment-ca-cert



# Synopsis

```
Usage:
  aptible environment:ca_cert

Options:
  --env, [--environment=ENVIRONMENT]

Retrieve the CA certificate associated with the environment
```

> 📘 Since most Database clients will want you to provide a PEM formatted certificate as a file, you will most likely want to simply redirect the output of this command directly to a file, eg: "aptible environment:ca\_cert &> all-aptible-CAs.pem" or "aptible environment:ca\_cert --environment=production &> production-CA.pem".


# aptible environment:list
Source: https://www.aptible.com/docs/reference/aptible-cli/cli-commands/cli-environment-list



This command lists all [Environments.](/docs/core-concepts/architecture/environments)

# Synopsis

```
Usage:
  aptible environment:list

Options:
  --env, [--environment=ENVIRONMENT]
```


# aptible environment:rename
Source: https://www.aptible.com/docs/reference/aptible-cli/cli-commands/cli-environment-rename



This command renames an [Environment](/docs/core-concepts/architecture/environments) handle. You must restart all the Apps and Databases in this Environment for the changes to take effect.

# Synopsis

```
Usage:
  aptible environment:rename OLD_HANDLE NEW_HANDLE
```


# aptible help
Source: https://www.aptible.com/docs/reference/aptible-cli/cli-commands/cli-help



This command displays available [commands](/docs/reference/aptible-cli/cli-commands/overview) or one specific command.

# Synopsis

```
Usage:
  aptible help [COMMAND]
```


# aptible log_drain:create:datadog
Source: https://www.aptible.com/docs/reference/aptible-cli/cli-commands/cli-log-drain-create-datadog



This command lets you create a [Log Drain](/docs/core-concepts/observability/logs/log-drains/overview) to forward your Container logs to Datadog.

> 📘 The `--url` option must use the format `https://http-intake.logs.datadoghq.com/v1/input/<DD_API_KEY>`. You can add tags as query parameters to filter logs in Datadog (for example, `?env=production`). Refer to [https://docs.datadoghq.com/logs/log\_collection](https://docs.datadoghq.com/logs/log_collection) for more options.

> Please note, Datadog's documentation defaults to v2. Please use v1 Datadog documentation with Aptible.

# Synopsis

```
Usage:
  aptible log_drain:create:datadog HANDLE --url DATADOG_URL --environment ENVIRONMENT [--drain-apps true/false] [--drain_databases true/false] [--drain_ephemeral_sessions true/false] [--drain_proxies true/false]

Options:
  [--drain-apps], [--no-drain-apps]
                                                                 # Default: true
  [--drain-databases], [--no-drain-databases]
                                                                 # Default: true
  [--drain-ephemeral-sessions], [--no-drain-ephemeral-sessions]
                                                                 # Default: true
  [--drain-proxies], [--no-drain-proxies]
                                                                 # Default: true
  --env, [--environment=ENVIRONMENT]
  [--url=URL]
```


# aptible log_drain:create:elasticsearch
Source: https://www.aptible.com/docs/reference/aptible-cli/cli-commands/cli-log-drain-create-elasticsearch



This command lets you create a [Log Drain](/docs/core-concepts/observability/logs/log-drains/overview) to forward your container logs to an [Elasticsearch Database](/docs/core-concepts/managed-databases/supported-databases/elasticsearch) hosted on Aptible.

> 📘 You must choose a destination Elasticsearch Database that is within the same Environment as the Log Drain you are creating.

# Synopsis

```
Usage:
  aptible log_drain:create:elasticsearch HANDLE --db DATABASE_HANDLE --environment ENVIRONMENT [--drain-apps true/false] [--drain_databases true/false] [--drain_ephemeral_sessions true/false] [--drain_proxies true/false]

Options:
  [--drain-apps], [--no-drain-apps]
                                                                 # Default: true
  [--drain-databases], [--no-drain-databases]
                                                                 # Default: true
  [--drain-ephemeral-sessions], [--no-drain-ephemeral-sessions]
                                                                 # Default: true
  [--drain-proxies], [--no-drain-proxies]
                                                                 # Default: true
  --env, [--environment=ENVIRONMENT]
  [--db=DB]
  [--pipeline=PIPELINE]
```


# aptible log_drain:create:https
Source: https://www.aptible.com/docs/reference/aptible-cli/cli-commands/cli-log-drain-create-https



This command lets you create a [Log Drain](/docs/core-concepts/observability/logs/log-drains/overview) to forward your container logs to an [HTTPS destination](/docs/core-concepts/observability/logs/log-drains/https-log-drains) of your choice.

> 📘 There are specific CLI commands for creating Log Drains for some specific HTTPS destinations, such as [Datadog](/docs/reference/aptible-cli/cli-commands/cli-log-drain-create-datadog), [LogDNA](/docs/reference/aptible-cli/cli-commands/cli-log-drain-create-logdna), and [SumoLogic](/docs/reference/aptible-cli/cli-commands/cli-log-drain-create-sumologic).

# Synopsis

```
Usage:
  aptible log_drain:create:https HANDLE --url URL --environment ENVIRONMENT [--drain-apps true/false] [--drain_databases true/false] [--drain_ephemeral_sessions true/false] [--drain_proxies true/false]

Options:
  [--url=URL]
  [--drain-apps], [--no-drain-apps]
                                                                 # Default: true
  [--drain-databases], [--no-drain-databases]
                                                                 # Default: true
  [--drain-ephemeral-sessions], [--no-drain-ephemeral-sessions]
                                                                 # Default: true
  [--drain-proxies], [--no-drain-proxies]
                                                                 # Default: true
  --env, [--environment=ENVIRONMENT]
```


# aptible log_drain:create:logdna
Source: https://www.aptible.com/docs/reference/aptible-cli/cli-commands/cli-log-drain-create-logdna



This command lets you create a [Log Drain](/docs/core-concepts/observability/logs/log-drains/overview) to forward your container logs to LogDNA.

> 📘 The `--url` options must be given in the format of `https://logs.logdna.com/aptible/ingest/<INGESTION KEY>`. Refer to [https://docs.logdna.com/docs/aptible-logs](https://docs.logdna.com/docs/aptible-logs) for more options.

# Synopsis

```
Usage:
  aptible log_drain:create:logdna HANDLE --url LOGDNA_URL --environment ENVIRONMENT [--drain-apps true/false] [--drain_databases true/false] [--drain_ephemeral_sessions true/false] [--drain_proxies true/false]

Options:
  [--url=URL]
  [--drain-apps], [--no-drain-apps]
                                                                 # Default: true
  [--drain-databases], [--no-drain-databases]
                                                                 # Default: true
  [--drain-ephemeral-sessions], [--no-drain-ephemeral-sessions]
                                                                 # Default: true
  [--drain-proxies], [--no-drain-proxies]
                                                                 # Default: true
  --env, [--environment=ENVIRONMENT]
```


# aptible log_drain:create:papertrail
Source: https://www.aptible.com/docs/reference/aptible-cli/cli-commands/cli-log-drain-create-papertrail



This command lets you create a [Log Drain](/docs/core-concepts/observability/logs/log-drains/overview) to forward your container logs to Papertrail.

> 📘 Note

> Add a new Log Destination in Papertrail (make sure to accept TCP + TLS connections and logs from unrecognized senders), then copy the host and port from the Log Destination.

# Synopsis

```
Usage:
  aptible log_drain:create:papertrail HANDLE --host PAPERTRAIL_HOST --port PAPERTRAIL_PORT --environment ENVIRONMENT [--drain-apps true/false] [--drain_databases true/false] [--drain_ephemeral_sessions true/false] [--drain_proxies true/false]

Options:
  [--host=HOST]
  [--port=PORT]
  [--drain-apps], [--no-drain-apps]
                                                                 # Default: true
  [--drain-databases], [--no-drain-databases]
                                                                 # Default: true
  [--drain-ephemeral-sessions], [--no-drain-ephemeral-sessions]
                                                                 # Default: true
  [--drain-proxies], [--no-drain-proxies]
                                                                 # Default: true
  --env, [--environment=ENVIRONMENT]

Create a Papertrail Log Drain
```


# aptible log_drain:create:solarwinds
Source: https://www.aptible.com/docs/reference/aptible-cli/cli-commands/cli-log-drain-create-solarwinds



This command lets you create a [Log Drain](/docs/core-concepts/observability/logs/log-drains/overview) to forward your container logs to SolarWinds.

> 📘 Note

> Aptible supports sending logs to SolarWinds securely via Syslog+TLS. Add a new manual type destination in SolarWinds, and provide the syslog hostname and token when creating the log drain.

# Synopsis

```
Usage:
  aptible log_drain:create:solarwinds HANDLE --host SWO_HOSTNAME --token SWO_TOKEN --environment ENVIRONMENT [--drain-apps|--no-drain-apps] [--drain-databases|--no-drain-databases] [--drain-ephemeral-sessions|--no-drain-ephemeral-sessions] [--drain_proxies|--no-drain-proxies]

Options:
  [--host=HOST]
  [--port=PORT]
  [--drain-apps], [--no-drain-apps]
                                                                 # Default: true
  [--drain-databases], [--no-drain-databases]
                                                                 # Default: true
  [--drain-ephemeral-sessions], [--no-drain-ephemeral-sessions]
                                                                 # Default: true
  [--drain-proxies], [--no-drain-proxies]
                                                                 # Default: true
  --env, [--environment=ENVIRONMENT]

Create a SolarWinds Log Drain.  By default, App, Database, Ephemeral Session, and Proxy logs will be sent to your chosen destination.
```


# aptible log_drain:create:sumologic
Source: https://www.aptible.com/docs/reference/aptible-cli/cli-commands/cli-log-drain-create-sumologic



This command lets you create a [Log Drain](/docs/core-concepts/observability/logs/log-drains/overview) to forward your container logs to Sumo Logic.

> 📘 Note

> Create a new Hosted Collector in Sumo Logic using a HTTP source, then use provided the HTTP Source Address for the `--url` option.

# Synopsis

```
Usage:
  aptible log_drain:create:sumologic HANDLE --url SUMOLOGIC_URL --environment ENVIRONMENT [--drain-apps true/false] [--drain_databases true/false] [--drain_ephemeral_sessions true/false] [--drain_proxies true/false]

Options:
  [--url=URL]
  [--drain-apps], [--no-drain-apps]
                                                                 # Default: true
  [--drain-databases], [--no-drain-databases]
                                                                 # Default: true
  [--drain-ephemeral-sessions], [--no-drain-ephemeral-sessions]
                                                                 # Default: true
  [--drain-proxies], [--no-drain-proxies]
                                                                 # Default: true
  --env, [--environment=ENVIRONMENT]

Create a Sumo Logic Drain
```


# aptible log_drain:create:syslog
Source: https://www.aptible.com/docs/reference/aptible-cli/cli-commands/cli-log-drain-create-syslog



This command lets you create a [Log Drain](/docs/core-concepts/observability/logs/log-drains/overview) to forward your container logs to an [Syslog TCP+TLS destination](/docs/core-concepts/observability/logs/log-drains/syslog-log-drains) of your choice.

> 📘 Note

> There are specific CLI commands for creating Log Drains for some specific Syslog destinations, such as [Papertrail](/docs/reference/aptible-cli/cli-commands/cli-log-drain-create-papertrail).

# Synopsis

```
Usage:
  aptible log_drain:create:syslog HANDLE --host SYSLOG_HOST --port SYSLOG_PORT [--token TOKEN] --environment ENVIRONMENT [--drain-apps true/false] [--drain_databases true/false] [--drain_ephemeral_sessions true/false] [--drain_proxies true/false]

Options:
  [--host=HOST]
  [--port=PORT]
  [--token=TOKEN]
  [--drain-apps], [--no-drain-apps]
                                                                 # Default: true
  [--drain-databases], [--no-drain-databases]
                                                                 # Default: true
  [--drain-ephemeral-sessions], [--no-drain-ephemeral-sessions]
                                                                 # Default: true
  [--drain-proxies], [--no-drain-proxies]
                                                                 # Default: true
  --env, [--environment=ENVIRONMENT]

Create a Papertrail Log Drain
```


# aptible log_drain:deprovision
Source: https://www.aptible.com/docs/reference/aptible-cli/cli-commands/cli-log-drain-deprovision



# Synopsis

```
Usage:
  aptible log_drain:deprovision HANDLE --environment ENVIRONMENT

Options:
  --env, [--environment=ENVIRONMENT]

Deprovisions a log drain
```


# aptible log_drain:list
Source: https://www.aptible.com/docs/reference/aptible-cli/cli-commands/cli-log-drain-list



This command lets you list the [Log Drains](/docs/core-concepts/observability/logs/log-drains/overview) you have configured for your [Environments](/docs/core-concepts/architecture/environments).

# Synopsis

```
Usage:
  aptible log_drain:list

Options:
  --env, [--environment=ENVIRONMENT]
```


# aptible login
Source: https://www.aptible.com/docs/reference/aptible-cli/cli-commands/cli-login



This command is used to login to Aptible from the CLI.\
\
Synopsis

```
Usage:
  aptible login

Options:
  [--email=EMAIL]
  [--password=PASSWORD]
  [--lifetime=LIFETIME]     # The duration the token should be valid for (example usage: 24h, 1d, 600s, etc.). When using SSO tokens, the effective lifetime is capped by your Identity Provider's session duration.
  [--otp-token=OTP_TOKEN]  # A token generated by your second-factor app
  [--sso=SSO]              # Use a token from a Single Sign On login on the dashboard
```


# aptible logs
Source: https://www.aptible.com/docs/reference/aptible-cli/cli-commands/cli-logs



This command lets you access real-time logs for an [App](/docs/core-concepts/apps/overview) or [Database](/docs/core-concepts/managed-databases/managing-databases/overview).

# Synopsis

```
Usage:
  aptible logs [--app APP | --database DATABASE]

Options:
      [--app=APP]
  --env, [--environment=ENVIRONMENT]
  -r, [--remote=REMOTE]
      [--database=DATABASE]
```

# Examples

## App logs

```shell theme={null}
aptible logs --app "$APP_HANDLE"
```

## Database logs

```shell theme={null}
aptible logs --database "$DATABASE_HANDLE"
```


# aptible logs_from_archive
Source: https://www.aptible.com/docs/reference/aptible-cli/cli-commands/cli-logs-from-archive



This command is used to retrieve container logs from your own [Disaster Log Archive](/docs/core-concepts/observability/logs/s3-log-archives).

> ❗️ You must have enabled log archiving for your Dedicated Stack(s) in order to use this command.

# Synopsis

```
Usage:
  aptible logs_from_archive --bucket NAME --region REGION --stack NAME [ --decryption-keys ONE [OR MORE] ] [ --download-location LOCATION ] [ [ --string-matches ONE [OR MORE] ] | [ --app-id ID | --database-id ID | --endpoint-id ID | --container-id ID ] [ --start-date YYYY-MM-DD --end-date YYYY-MM-DD ] ] --bucket=BUCKET --region=REGION --stack=STACK

Options:
  --region=REGION                          # The AWS region your S3 bucket resides in
  --bucket=BUCKET                          # The name of your S3 bucket
  --stack=STACK                            # The name of the Stack to download logs from
  [--decryption-keys=one two three]        # The Aptible-provided keys for decryption. (Space separated if multiple)
  [--string-matches=one two three]         # The strings to match in log file names.(Space separated if multiple)
  [--app-id=N]                             # The Application ID to download logs for.
  [--database-id=N]                        # The Database ID to download logs for.
  [--endpoint-id=N]                        # The Endpoint ID to download logs for.
  [--container-id=CONTAINER_ID]            # The container ID to download logs for
  [--start-date=START_DATE]                # Get logs starting from this (UTC) date (format: YYYY-MM-DD)
  [--end-date=END_DATE]                    # Get logs before this (UTC) date (format: YYYY-MM-DD)
  [--download-location=DOWNLOAD_LOCATION]  # The local path place downloaded log files. If you do not set this option, the file names will be shown, but not downloaded.

Retrieves container logs from an S3 archive in your own AWS account. You must provide your AWS credentials via the environment variables AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY
```

> 📘 You can find resource ID's by looking at the URL of a resource on the Aptible Dashboard, or by using the [JSON output format](/docs/reference/aptible-cli/cli-commands/overview#output-format) for the [`aptible db:list`](/docs/reference/aptible-cli/cli-commands/cli-db-list) or [`aptible apps`](/docs/reference/aptible-cli/cli-commands/cli-apps) commands.

> This command also allows retrieval of logs from deleted resources. Please contact [Aptible Support](/docs/how-to-guides/troubleshooting/aptible-support) for assistance identifying the proper resource IDs of deleted resources.

# Examples

## Search for all archived logs for a specific Database

By default, no logs are downloaded. Matching file names are printed on the screen.

```shell theme={null}
aptible logs_from_archive --database-id "$ID" \
        --stack "$STACK" \
        --region "$REGION" \
        --decryption-keys "$KEY"
```

## Search for archived logs for a specific Database within a specific date range

You can specify a date range in UTC to limit the search to logs emitted during a time period.

```shell theme={null}
aptible logs_from_archive --database-id "$ID" --start-date "2022-08-30" --end-date "2022-10-03" \
        --stack "$STACK" \
        --region "$REGION" \
        --decryption-keys "$KEY"
```

## Download logs from a specific App to a local path

Once you have identified the files you wish to download, add the `--download-location` parameter to download the files to your local system.

> ❗️ Warning: Since container logs may include PHI or sensitive credentials, please choose the download location carefully.

```shell theme={null}
aptible logs_from_archive --app-id "$ID" --download-location "$LOCAL_PATH" \
        --stack "$STACK" \
        --region "$REGION" \
        --decryption-keys "$KEY"
```

## Search for logs from a specific Container

You can search for logs for a specific container if you know the container ID.

```shell theme={null}
aptible logs_from_archive --container-id "$ID" \
        --stack "$STACK" \
        --region "$REGION" \
        --decryption-keys "$KEY"
```


# aptible maintenance:apps
Source: https://www.aptible.com/docs/reference/aptible-cli/cli-commands/cli-maintenance-apps



This command lists [Apps](/docs/core-concepts/apps/overview) with pending maintenance.

# Synopsis

```
Usage:
  aptible maintenance:apps

Options:
  --env, [--environment=ENVIRONMENT]
```


# aptible maintenance:dbs
Source: https://www.aptible.com/docs/reference/aptible-cli/cli-commands/cli-maintenance-dbs



This command lists [Databases](/docs/core-concepts/managed-databases/overview) with pending maintenance.

# Synopsis

```
Usage:
  aptible maintenance:dbs

Options:
  --env, [--environment=ENVIRONMENT]
```


# aptible metric_drain:create:datadog
Source: https://www.aptible.com/docs/reference/aptible-cli/cli-commands/cli-metric-drain-create-datadog



This command lets you create a [Metric Drain](/docs/core-concepts/observability/metrics/metrics-drains/overview) to forward your container metrics to [Datadog](/docs/core-concepts/integrations/datadog).

You need to use the `--site` option to specify the [Datadog Site](https://docs.datadoghq.com/getting_started/site/) associated with your Datadog account. Valid options are `US1`, `US3`, `US5`, `EU1`, or `US1-FED`

# Synopsis

```
Usage:
  aptible metric_drain:create:datadog HANDLE --api_key DATADOG_API_KEY --site DATADOG_SITE --environment ENVIRONMENT

Options:
  [--api-key=API_KEY]
  [--site=SITE]
  --env, [--environment=ENVIRONMENT]
```


# aptible metric_drain:create:influxdb
Source: https://www.aptible.com/docs/reference/aptible-cli/cli-commands/cli-metric-drain-create-influxdb



This command lets you create a [Metric Drain](/docs/core-concepts/observability/metrics/metrics-drains/overview) to forward your container metrics to an [InfluxDB Database](/docs/core-concepts/managed-databases/supported-databases/influxdb) hosted on Aptible.

> 📘 You must choose a destination InfluxDB Database that is within the same Environment as the Metric Drain you are creating.

# Synopsis

```
Usage:
  aptible metric_drain:create:influxdb HANDLE --db DATABASE_HANDLE --environment ENVIRONMENT

Options:
  [--db=DB]
  --env, [--environment=ENVIRONMENT]
```


# aptible metric_drain:create:influxdb:custom
Source: https://www.aptible.com/docs/reference/aptible-cli/cli-commands/cli-metric-drain-create-influxdb-custom



This command lets you create a [Metric Drain](/docs/core-concepts/observability/metrics/metrics-drains/overview) to forward your container metrics to an InfluxDB database hosted outside Aptible.

> 📘 Only InfluxDB v1 destinations are supported.

# Synopsis

```
Usage:
  aptible metric_drain:create:influxdb:custom HANDLE --username USERNAME --password PASSWORD --url URL_INCLUDING_PORT --db INFLUX_DATABASE_NAME --environment ENVIRONMENT

Options:
  [--db=DB]
  [--username=USERNAME]
  [--password=PASSWORD]
  [--url=URL]
  --env, [--environment=ENVIRONMENT]
```


# aptible metric_drain:create:influxdb:customv2
Source: https://www.aptible.com/docs/reference/aptible-cli/cli-commands/cli-metric-drain-create-influxdb-customv2



This command lets you create a [Metric Drain](/docs/core-concepts/observability/metrics/metrics-drains/overview) to forward your container metrics to an InfluxDB v2 database hosted outside Aptible.

> 📘 This command is for InfluxDB v2 destinations, which use organizations, buckets, and tokens for authentication. For InfluxDB v1 (which uses databases, usernames, and passwords), use [metric\_drain:create:influxdb:custom](/docs/reference/aptible-cli/cli-commands/cli-metric-drain-create-influxdb-custom).

# Synopsis

```
Usage:
  aptible metric_drain:create:influxdb:customv2 HANDLE --org ORGANIZATION --token INFLUX_TOKEN --url URL_INCLUDING_PORT --bucket INFLUX_BUCKET_NAME --environment ENVIRONMENT

Options:
  [--bucket=BUCKET]
  [--org=ORG]
  [--token=TOKEN]
  [--url=URL]
  --env, [--environment=ENVIRONMENT]
```

# Examples

```bash theme={null}
aptible metric_drain:create:influxdb:customv2 my-influxdb-v2-drain \
  --org my-org \
  --token my-influxdb-auth-token \
  --url https://influxdb.example.com:8086 \
  --bucket production-metrics \
  --environment production
```

# Related Commands

* [aptible metric\_drain:list](/docs/reference/aptible-cli/cli-commands/cli-metric-drain-list) - List all metric drains
* [aptible metric\_drain:create:influxdb](/docs/reference/aptible-cli/cli-commands/cli-metric-drain-create-influxdb) - Create a metric drain for InfluxDB hosted on Aptible
* [aptible metric\_drain:create:influxdb:custom](/docs/reference/aptible-cli/cli-commands/cli-metric-drain-create-influxdb-custom) - Create a metric drain for external InfluxDB v1
* [aptible metric\_drain:deprovision](/docs/reference/aptible-cli/cli-commands/cli-metric-drain-deprovision) - Remove a metric drain


# aptible metric_drain:deprovision
Source: https://www.aptible.com/docs/reference/aptible-cli/cli-commands/cli-metric-drain-deprovision



This command deprovisions a [Metric Drain](/docs/core-concepts/observability/metrics/metrics-drains/overview).

# Synopsis

```
Usage:
  aptible metric_drain:deprovision HANDLE --environment ENVIRONMENT

Options:
  --env, [--environment=ENVIRONMENT]
```


# aptible metric_drain:list
Source: https://www.aptible.com/docs/reference/aptible-cli/cli-commands/cli-metric-drain-list



This command lets you list the [Metric Drains](/docs/core-concepts/observability/metrics/metrics-drains/overview) you have configured for your [Environments](/docs/core-concepts/architecture/environments).

# Synopsis

```
Usage:
  aptible metric_drain:list

Options:
  --env, [--environment=ENVIRONMENT]
```


# aptible operation:cancel
Source: https://www.aptible.com/docs/reference/aptible-cli/cli-commands/cli-operation-cancel



This command cancels a running [Operation.](/docs/core-concepts/architecture/operations)

# Synopsis

```
Usage:
  aptible operation:cancel OPERATION_ID
```


# aptible operation:follow
Source: https://www.aptible.com/docs/reference/aptible-cli/cli-commands/cli-operation-follow



This command follows the logs of a running [Operation](/docs/core-concepts/architecture/operations). Only the user that created an operation can successfully follow its logs via the CLI.

# Synopsis

```
Usage:
  aptible operation:follow OPERATION_ID
```


# aptible operation:logs
Source: https://www.aptible.com/docs/reference/aptible-cli/cli-commands/cli-operation-logs



This command displays logs for a given [operation](/docs/core-concepts/architecture/operations) performed within the last 90 days.

# Synopsis

```
Usage:
  aptible operation:logs OPERATION_ID
```


# aptible organizations
Source: https://www.aptible.com/docs/reference/aptible-cli/cli-commands/cli-organizations



This command lists all organizations you have access to, along with your roles in each organization.

# Synopsis

```
Usage:
  aptible organizations

Options:
  None
```

# Output

The command displays each organization with its ID, name, and your roles within that organization.

## Text Format

By default, the command outputs in a human-readable text format:

```
Id: 5ca1ab1e-0000-0000-0000-000000000000
Name: Acme Prod
Roles:
  Id: 5afe5afe-0000-0000-0000-000000000000
  Name: Deploy Owners

  Id: acce5500-0000-0000-0000-000000000000
  Name: Read Only

Id: cafecafe-cafe-cafe-cafe-cafecafecafe
Name: Acme Test
Roles:
  Id: c0ffee50-0000-0000-0000-000000000000
  Name: Account Owners
```

## JSON Format

Set the `APTIBLE_OUTPUT_FORMAT=json` environment variable for machine-readable JSON output:

```shell theme={null}
APTIBLE_OUTPUT_FORMAT=json aptible organizations
```

```json theme={null}
[
  {
    "id": "5ca1ab1e-0000-0000-0000-000000000000",
    "name": "Acme Prod",
    "roles": [
      {
        "id": "5afe5afe-0000-0000-0000-000000000000",
        "name": "Deploy Owners"
      },
      {
        "id": "acce5500-0000-0000-0000-000000000000",
        "name": "Read Only"
      }
    ]
  },
  {
    "id": "cafecafe-cafe-cafe-cafe-cafecafecafe",
    "name": "Acme Test",
    "roles": [
      {
        "id": "c0ffee50-0000-0000-0000-000000000000",
        "name": "Account Owners"
      }
    ]
  }
]
```

# Examples

```shell theme={null}
aptible organizations
```

```shell theme={null}
APTIBLE_OUTPUT_FORMAT=json aptible organizations
```

# Related Commands

* [aptible environment:list](/docs/reference/aptible-cli/cli-commands/cli-environment-list) - List environments within an organization
* [aptible login](/docs/reference/aptible-cli/cli-commands/cli-login) - Log in to Aptible


# aptible rebuild
Source: https://www.aptible.com/docs/reference/aptible-cli/cli-commands/cli-rebuild



This command rebuilds an [App](/docs/core-concepts/apps/overview) and restarts its [Services](/docs/core-concepts/apps/deploying-apps/services).

# Synopsis

```
Usage:
  aptible rebuild [--app APP]

Options:
      [--app=APP]
  --env, [--environment=ENVIRONMENT]
  -r, [--remote=REMOTE]
```


# aptible restart
Source: https://www.aptible.com/docs/reference/aptible-cli/cli-commands/cli-restart



This command restarts an [App](/docs/core-concepts/apps/overview) and all its associated [Services](/docs/core-concepts/apps/deploying-apps/services).

# Synopsis

```
Usage:
  aptible restart [--app APP]

Options:
      [--simulate-oom], [--no-simulate-oom]  # Add this flag to simulate an OOM restart and test your app's response (not recommended on production apps).
      [--force]                              # Add this flag to use --simulate-oom in a production environment, which is not allowed by default.
      [--app=APP]
  --env, [--environment=ENVIRONMENT]
  -r, [--remote=REMOTE]
```

# Examples

```shell theme={null}
aptible restart --app "$APP_HANDLE"
```


# aptible services
Source: https://www.aptible.com/docs/reference/aptible-cli/cli-commands/cli-services



This command lists all [Services](/docs/core-concepts/apps/deploying-apps/services) for a given [App](/docs/core-concepts/apps/overview).

# Synopsis

```
Usage:
  aptible services [--app APP]

Options:
      [--app=APP]
  --env, [--environment=ENVIRONMENT]
  -r, [--remote=REMOTE]
```


# aptible services:autoscaling_policy
Source: https://www.aptible.com/docs/reference/aptible-cli/cli-commands/cli-services-autoscalingpolicy



Returns the associated sizing (autoscaling) policy, if any. Also aliased to `services:sizing_policy`.

For more information, see the [Autoscaling documentation](/docs/core-concepts/scaling/app-scaling)

# Synopsis

```
Usage:
  aptible services:autoscaling_policy [--app APP] SERVICE

Options:
      [--app=APP]
  --env, [--environment=ENVIRONMENT]
  -r, [--remote=REMOTE]
```


# aptible services:autoscaling_policy:set
Source: https://www.aptible.com/docs/reference/aptible-cli/cli-commands/cli-services-autoscalingpolicy-set



Sets the sizing (autoscaling) policy for a service. This is not incremental, all arguments must be sent at once or they will be set to defaults. Also aliased to `services:sizing_policy:set`.

For more information, see the [Autoscaling documentation](/docs/core-concepts/scaling/app-scaling)

# Synopsis

```
Usage:
  aptible services:autoscaling_policy:set [--app APP] SERVICE --autoscaling-type (horizontal|vertical) [--metric-lookback-seconds SECONDS] [--percentile PERCENTILE] [--post-scale-up-cooldown-seconds SECONDS] [--post-scale-down-cooldown-seconds SECONDS] [--post-release-cooldown-seconds SECONDS] [--mem-cpu-ratio-r-threshold RATIO] [--mem-cpu-ratio-c-threshold RATIO] [--mem-scale-up-threshold THRESHOLD] [--mem-scale-down-threshold THRESHOLD] [--minimum-memory MEMORY] [--maximum-memory MEMORY] [--min-cpu-threshold THRESHOLD] [--max-cpu-threshold THRESHOLD] [--min-containers CONTAINERS] [--max-containers CONTAINERS] [--scale-up-step STEPS] [--scale-down-step STEPS]

Options:
      [--app=APP]
  --env, [--environment=ENVIRONMENT]
  -r, [--remote=REMOTE]
      [--autoscaling-type=AUTOSCALING_TYPE]                # The type of autoscaling. Must be either "horizontal" or "vertical"
      [--metric-lookback-seconds=N]                        # (Default: 1800) The duration in seconds for retrieving past performance metrics.
      [--percentile=N]                                     # (Default: 99) The percentile for evaluating metrics.
      [--post-scale-up-cooldown-seconds=N]                 # (Default: 60) The waiting period in seconds after an automated scale-up before another scaling action can be considered.
      [--post-scale-down-cooldown-seconds=N]               # (Default: 300) The waiting period in seconds after an automated scale-down before another scaling action can be considered.
      [--post-release-cooldown-seconds=N]                  # (Default: 60) The time in seconds to ignore in metrics following a deploy to allow for service stabilization.
      [--mem-cpu-ratio-r-threshold=N]                      # (Default: 4.0) Establishes the ratio of Memory (in GB) to CPU (in CPUs) at which values exceeding the threshold prompt a shift to an R (Memory Optimized) profile.
      [--mem-cpu-ratio-c-threshold=N]                      # (Default: 2.0) Sets the Memory-to-CPU ratio threshold, below which the service is transitioned to a C (Compute Optimized) profile.
      [--mem-scale-up-threshold=N]                         # (Default: 0.9) Vertical autoscaling only - Specifies a threshold based on a percentage of the current memory limit at which the service's memory usage triggers a scale up.
      [--mem-scale-down-threshold=N]                       # (Default: 0.75) Vertical autoscaling only - Specifies a threshold based on the percentage of the next smallest container size's memory limit at which the service's memory usage triggers a scale down.
      [--minimum-memory=N]                                 # (Default: 2048) Vertical autoscaling only - Sets the lowest memory limit to which the service can be scaled down by Autoscaler.
      [--maximum-memory=N]                                 # Vertical autoscaling only - Defines the upper memory threshold, capping the maximum memory allocation possible through Autoscaler. If blank, the container can scale to the largest size available.
      [--min-cpu-threshold=N]                              # Horizontal autoscaling only - Specifies the percentage of the current CPU usage at which a down-scaling action is triggered.
      [--max-cpu-threshold=N]                              # Horizontal autoscaling only - Specifies the percentage of the current CPU usage at which an up-scaling action is triggered.
      [--min-containers=N]                                 # Horizontal autoscaling only - Sets the lowest container count to which the service can be scaled down.
      [--max-containers=N]                                 # Horizontal autoscaling only - Sets the highest container count to which the service can be scaled up to.
      [--restart-free-scale|--no-restart-free-scale]       # Horizontal autoscaling only - Sets the autoscaling to use a restart-free scaling strategy.
      [--scale-up-step=N]                                  # (Default: 1) Horizontal autoscaling only - Sets the amount of containers to add when autoscaling (ex: a value of 2 will go from 1->3->5). Container count will never exceed the configured maximum.
      [--scale-down-step=N]                                # (Default: 1) Horizontal autoscaling only - Sets the amount of containers to remove when autoscaling (ex: a value of 2 will go from 4->2->1). Container count will never exceed the configured minimum.
```


# aptible services:settings
Source: https://www.aptible.com/docs/reference/aptible-cli/cli-commands/cli-services-settings



This command lets you configure [Services](/docs/core-concepts/apps/deploying-apps/services) for a given [App](/docs/core-concepts/apps/overview).

# Synopsis

```
Usage:
  aptible services:settings [--app APP] SERVICE [--force-zero-downtime|--no-force-zero-downtime] [--simple-health-check|--no-simple-health-check] [--restart-free-scaling|--no-restart-free-scaling] [--stop-timeout SECONDS]

Options:
      [--app=APP]
  --env, [--environment=ENVIRONMENT]
  -r, [--remote=REMOTE]
      [--force-zero-downtime|--no-force-zero-downtime]
      [--simple-health-check|--no-simple-health-check]
      [--restart-free-scaling|--no-restart-free-scaling]
      [--stop-timeout=SECONDS]
```

# Examples

```shell theme={null}
aptible services:settings --app "$APP_HANDLE" SERVICE \
        --force-zero-downtime \
        --simple-health-check
```

```shell theme={null}
aptible services:settings --app "$APP_HANDLE" SERVICE \
        --stop-timeout 60
```

#### Force Zero Downtime

For Services without endpoints, you can force a zero downtime deployment strategy, which enables healthchecks via Docker's healthcheck mechanism.

#### Simple Health Check

When enabled, instead of using Docker healthchecks, Aptible will ensure your container can stay up for 30 seconds before continuing the deployment.

#### Restart Free Scaling

When enabled, scaling operations that only change the number of containers will not restart existing containers.


# aptible ssh
Source: https://www.aptible.com/docs/reference/aptible-cli/cli-commands/cli-ssh



This command creates [Ephemeral SSH Sessions](/docs/core-concepts/apps/connecting-to-apps/ssh-sessions) to [Apps](/docs/core-concepts/apps/overview) running on Aptible.

# Synopsis

```
Usage:
  aptible ssh [--app APP] [COMMAND]

Options:
      [--app=APP]
  --env, [--environment=ENVIRONMENT]
  -r, [--remote=REMOTE]
      [--force-tty], [--no-force-tty]

Description:
  Runs an interactive command against a remote Aptible app

  If specifying an app, invoke via: aptible ssh [--app=APP] COMMAND
```

# Examples

```shell theme={null}
aptible ssh --app "$APP_HANDLE"
```


# aptible version
Source: https://www.aptible.com/docs/reference/aptible-cli/cli-commands/cli-version



This command prints the version of the Aptible CLI running.

# Synopsis

```
Usage:
  aptible version
```


# CLI Configurations
Source: https://www.aptible.com/docs/reference/aptible-cli/cli-configurations

The Aptible CLI provides configuration options such as MFA support, customizing output format, and overriding configuration location.

## MFA support

To use hardware-based MFA (e.g., Yubikey) on Windows and Linux, manually install the libfido2 command line tools. You can find the latest installation release and installation instructions [here](https://developers.yubico.com/libfido2/).

For OSX users, installation via Homebrew will automatically include the libfido2 dependency.

## Output Format

The Aptible CLI supports two output formats: plain text and JSON. You can select your preferred output format by setting the `APTIBLE_OUTPUT_FORMAT` environment variable to `text` or `json`.

If the `APTIBLE_OUTPUT_FORMAT` variable is left unset (i.e., the default), the CLI will provide output as plain text.

> 📘 The Aptible CLI sends logging output to `stderr`, and everything else to `stdout` (this is the standard behavior for well-behaved UNIX programs).

> If you're calling the Aptible CLI from another program, make sure you don't merge the two streams (if you did, you'd have to filter out the logging output).

> Note that if you're simply using a shell such as Bash, the pipe operator (i.e. `|`) only pipes `stdout` through, which is exactly what you want here.

## Configuration location

The Aptible CLI normally stores its configuration (your Aptible authentication token and automatically generated SSH keys) in a hidden subfolder of your home directory: `~/.aptible`. To override this default location, you can specify a custom path by using the environment variable `APTIBLE_CONFIG_PATH`. Since the files in this path grant access to your Aptible account, protect them as if they were your password itself!


# Aptible CLI - Overview
Source: https://www.aptible.com/docs/reference/aptible-cli/overview

Learn more about using the Aptible CLI for managing resources

# Overview

The Aptible CLI is a tool to help you manage your Aptible resources directly from the command line. You can use the Aptible CLI to do things like:

Create, modify, and delete Aptible resources
Deploy, restart, and scale Apps and Databases
View real-time logs
For an overview of what features the CLI supports, see the Feature Support Matrix.

# Install the Aptible CLI

<Tabs>
  <Tab title="MacOS">
    [](https://omnibus-aptible-toolbelt.s3.us-east-1.amazonaws.com/aptible/omnibus-aptible-toolbelt/master/gh-89/pkg/aptible-toolbelt-0.26.8%2B20260608224702-mac-os-x.10.15.7-1.pkg)Install v0.26.8 with **Homebrew**

    ```
    brew install --cask aptible
    ```
  </Tab>

  <Tab title="Windows">
    [Download v0.26.8 for Windows ↓](https://omnibus-aptible-toolbelt.s3.us-east-1.amazonaws.com/aptible/omnibus-aptible-toolbelt/master/gh-89/pkg/aptible-toolbelt-0.26.8%2B20260608224825~windows.6.3.9600-1-x64.msi)
  </Tab>

  <Tab title="Debian">
    [Download v0.26.8 for Debian ↓](https://omnibus-aptible-toolbelt.s3.amazonaws.com/aptible/omnibus-aptible-toolbelt/latest/aptible-toolbelt_latest_debian-9_amd64.deb)
  </Tab>

  <Tab title="Ubuntu">
    [Download v0.26.8 for Ubuntu ↓](https://omnibus-aptible-toolbelt.s3.amazonaws.com/aptible/omnibus-aptible-toolbelt/latest/aptible-toolbelt_latest_ubuntu-1604_amd64.deb)
  </Tab>

  <Tab title="CentOS">
    [Download v0.26.8 for CentOS ↓](https://omnibus-aptible-toolbelt.s3.amazonaws.com/aptible/omnibus-aptible-toolbelt/latest/aptible-toolbelt_latest_centos-7_amd64.rpm)
  </Tab>
</Tabs>

# Try the CLI

Take the CLI for a spin with these commands or [browse through all available commands.](https://www.aptible.com/docs/commands)

<CodeGroup>
  ```python Login to the CLI theme={null}
  aptible login
  ```

  ```python View all commands theme={null}
  aptible help
  ```

  ```python Create a new app theme={null}
  aptible apps:create HANDLE --environment=ENVIRONMENT
  ```

  ```python List all databases theme={null}
  aptible db:list
  ```
</CodeGroup>


# Aptible Metadata Variables
Source: https://www.aptible.com/docs/reference/aptible-metadata-variables



Aptible injects the following metadata keys as environment variables:

* `APTIBLE_PROCESS_TYPE`

  * Represents the name of the [Service](/docs/core-concepts/apps/deploying-apps/services) this container belongs to. For example, if the [Procfile](/docs/how-to-guides/app-guides/define-services) defines services like `web` and `worker`.

  * Then, the containers for the web Service will run with `APTIBLE_PROCESS_TYPE=web`, and the containers for the worker Service will run with `APTIBLE_PROCESS_TYPE=worker`.

  * If there is no Procfile and users choose to use an [Implicit Service](/docs/how-to-guides/app-guides/define-services#implicit-service-cmd) instead, the variable is set to `APTIBLE_PROCESS_TYPE=cmd`.

* `APTIBLE_PROCESS_INDEX`

  * All containers for a given [Release](/docs/core-concepts/apps/deploying-apps/releases/overview) of a Service are assigned a unique 0-based process index.

  * For example, if your web service is [scaled](/docs/core-concepts/scaling/overview) to 2 containers, one will have `APTIBLE_PROCESS_INDEX=0`, and the other will have `APTIBLE_PROCESS_INDEX=1`.

* `APTIBLE_PROCESS_CONTAINER_COUNT`

  * This variable is a companion to `APTIBLE_PROCESS_INDEX`, and represents the total count of containers on the service. Note that this will only be present in app service containers (not in pre\_release, ephemeral/ssh, or database containers).

* `APTIBLE_CONTAINER_CPU_SHARE`

  * Provides the vCPU share for the container, matching the ratios in our documentation for [­container profiles](/docs/core-concepts/scaling/container-profiles). Format will be provided in the following format: 0.125, 0.5, 1.0, etc.

* `APTIBLE_CONTAINER_PROFILE`

* `APTIBLE_CONTAINER_SIZE`

  * This variable represents the memory limit in MB of the Container. See [Memory Limits](/docs/core-concepts/scaling/memory-limits) for more information.

* `APTIBLE_LAYER`

  * This variable represents whether the container is an [App](/docs/core-concepts/apps/overview) or [Database](/docs/core-concepts/managed-databases/managing-databases/overview) container using App or Database values.

* `APTIBLE_GIT_REF`

* `APTIBLE_ORGANIZATION_HREF`

  * Aptible API URL representing the [Organization](/docs/core-concepts/security-compliance/access-permissions) this container belongs to.

* `APTIBLE_APP_HREF`

  * Aptible API URL representing the [App](/docs/core-concepts/apps/overview) this container belongs to, if any.

* `APTIBLE_DATABASE_HREF`

  * Aptible API URL representing the [Database](/docs/core-concepts/managed-databases/managing-databases/overview) this container belongs to, if any.

* `APTIBLE_SERVICE_HREF`

  * Aptible API URL representing the Service this container belongs to, if any.

* `APTIBLE_RELEASE_HREF`

  * Aptible API URL representing the Release this container belongs to, if any.

* `APTIBLE_EPHEMERAL_SESSION_HREF`

  * Aptible API URL representing the current [Ephemeral SSH Sessions](/docs/core-concepts/apps/connecting-to-apps/ssh-sessions) this container belongs to, if any.

* `APTIBLE_USER_DOCUMENT`

  * Aptible injects an expired JWT object with user information.
    * The information available is id, email, name, etc.
    * Only available in [Ephemeral SSH Sessions](/docs/core-concepts/apps/connecting-to-apps/ssh-sessions).

  ```
  decode_base64_url() {
      local len=$((${#1} % 4))
      local result="$1"
      if [ $len -eq 2 ]; then result="$1"'=='
      elif [ $len -eq 3 ]; then result="$1"'=' 
      fi
      echo "$result" | tr '_-' '/+' | openssl enc -d -base64
  }

  decode_jwt(){
      decode_base64_url $(echo -n $2 | cut -d "." -f $1) | sed 's/{/\n&\n/g;s/}/\n&\n/g;s/,/\n&\n/g' | sed 's/^  */  /'
  }

  # Decode JWT header
  alias jwth="decode_jwt 1"

  # Decode JWT Payload
  alias jwtp="decode_jwt 2"
  ```

  You can use the above script to decode the expired JWT object using `jwtp $APTIBLE_USER_DOCUMENT`

* `APTIBLE_RESOURCE_HREF`

  * Aptible uses this variable internally. Do not depend on this value.

* `APTIBLE_ALLOCATION`

  * Aptible uses this variable internally. Do not depend on this value.


# Interface Feature Availability Matrix Guide
Source: https://www.aptible.com/docs/reference/interface-feature



There are three supported methods for managing resources on Aptible:

* [The Aptible Dashboard](/docs/reference/dashboard)
* The [Aptible CLI](/docs/reference/aptible-cli/cli-commands/overview) client
* The [Aptible Terraform Provider](https://registry.terraform.io/providers/aptible/aptible)

Currently, not every action is supported by every interface. This matrix describes which actions are supported by which interfaces.

## Key

* ✅ - Supported
* 🔶 - Partial Support
* ❌ - Not Supported
* 🚧 - In Progress
* N/A - Not Applicable

## Matrix

|                                   |              Web             | CLI | Terraform       |
| :-------------------------------: | :--------------------------: | :-: | --------------- |
|    **User Account Management**    |               ✅              |  ❌  | ❌               |
|    **Organization Management**    |               ✅              |  ❌  | ❌               |
|   **Dedicated Stack Management**  |                              |     |                 |
|               Create              | 🔶 (can request first stack) |  ❌  | ❌               |
|                List               |               ✅              |  ❌  | ✅ (data source) |
|            Deprovision            |               ❌              |  ❌  | ❌               |
|     **Environment Management**    |                              |     |                 |
|               Create              |               ✅              |  ❌  | ✅               |
|                List               |               ✅              |  ✅  | ✅ (data source) |
|               Delete              |               ✅              |  ❌  | ✅               |
|               Rename              |               ✅              |  ✅  | ✅               |
|    Set Backup Retention Policy    |               ✅              |  ✅  | ✅               |
|         Get CA Certificate        |               ❌              |  ✅  | ❌               |
|         **App Management**        |                              |     |                 |
|               Create              |               ✅              |  ✅  | ✅               |
|                List               |               ✅              |  ✅  | N/A             |
|            Deprovision            |               ✅              |  ✅  | ✅               |
|               Rename              |               ✅              |  ✅  | ✅               |
|               Deploy              |               ✅              |  ✅  | ✅               |
|        Update Configuration       |               ✅              |  ✅  | ✅               |
|         Get Configuration         |               ✅              |  ✅  | ✅               |
|            SSH/Execute            |              N/A             |  ✅  | N/A             |
|              Rebuild              |               ❌              |  ✅  | N/A             |
|              Restart              |               ✅              |  ✅  | N/A             |
|               Scale               |               ✅              |  ✅  | ✅               |
|            Autoscaling            |               ✅              |  ✅  | ✅               |
|     Change Container Profiles     |               ✅              |  ✅  | ✅               |
|      **Database Management**      |                              |     |                 |
|               Create              |     🔶 (limited versions)    |  ✅  | ✅               |
|                List               |               ✅              |  ✅  | N/A             |
|            Deprovision            |               ✅              |  ✅  | ✅               |
|               Rename              |               ✅              |  ✅  | ✅               |
|               Modify              |               ❌              |  ✅  | ❌               |
|               Reload              |               ❌              |  ✅  | N/A             |
|           Restart/Scale           |               ✅              |  ✅  | ✅               |
|     Change Container Profiles     |               ✅              |  ❌  | ✅               |
|          Get Credentials          |               ✅              |  ✅  | ✅               |
|          Create Replicas          |               ❌              |  ✅  | ✅               |
|               Tunnel              |              N/A             |  ✅  | ❌               |
|   **Database Backup Management**  |                              |     |                 |
|               Create              |               ✅              |  ✅  | N/A             |
|                List               |               ✅              |  ✅  | N/A             |
|               Delete              |               ✅              |  ✅  | N/A             |
|              Restore              |               ✅              |  ✅  | N/A             |
|          Disable backups          |               ✅              |  ❌  | ✅               |
|      **Endpoint Management**      |                              |     |                 |
|               Create              |               ✅              |  ✅  | ✅               |
|                List               |               ✅              |  ✅  | N/A             |
|            Deprovision            |               ✅              |  ✅  | ✅               |
|               Modify              |               ✅              |  ✅  | ✅               |
|            IP Filtering           |               ✅              |  ✅  | ✅               |
|        Custom Certificates        |               ✅              |  ✅  | ❌               |
| **Custom Certificate Management** |                              |     |                 |
|               Create              |               ✅              |  ❌  | ❌               |
|                List               |               ✅              |  ❌  | N/A             |
|               Delete              |               ✅              |  ❌  | ❌               |
|      **Log Drain Management**     |                              |     |                 |
|               Create              |               ✅              |  ✅  | ✅               |
|                List               |               ✅              |  ✅  | N/A             |
|            Deprovision            |               ✅              |  ✅  | ✅               |
|    **Metric Drain Management**    |                              |     |                 |
|               Create              |               ✅              |  ✅  | ✅               |
|                List               |               ✅              |  ✅  | N/A             |
|            Deprovision            |               ✅              |  ✅  | ✅               |
|      **Operation Management**     |                              |     |                 |
|                List               |               ✅              |  ❌  | N/A             |
|               Cancel              |               ❌              |  ✅  | N/A             |
|                Logs               |               ✅              |  ✅  | N/A             |
|               Follow              |              N/A             |  ✅  | N/A             |


# Pricing
Source: https://www.aptible.com/docs/reference/pricing

Learn about Aptible's pricing

# Aptible Hosted Pricing

The Aptible Hosted option allows organizations to provision infrastructure fully hosted by Aptible. This is ideal for organizations that prefer not to manage their own infrastructure and/or are looking to quickly get started. With this offering, the Aptible platform fee and infrastructure costs are wrapped into a simple, usage-based pricing model.

<CardGroup>
  <Card title="Get started in minutes" icon="sparkles">
    Instantly deploy apps & databases
  </Card>

  <Card title="Simple pricing, fully on-demand" icon="play-pause">
    Pay-as-you-go, no contract required
  </Card>

  <Card title="Fast track compliance" icon="shield-halved">
    Infrastructure for ready for HIPAA, SOC 2, HITRUST & more
  </Card>
</CardGroup>

### On-Demand Pricing

|                                 | Cost                                                    | Docs                                                                                       |
| ------------------------------- | ------------------------------------------------------- | ------------------------------------------------------------------------------------------ |
| **Compute**                     |                                                         |                                                                                            |
| General Purpose (M) Containers  | \$0.08/GB RAM/hour                                      | [→](/docs/core-concepts/scaling/container-profiles)                                             |
| CPU-Optimized (C) Containers    | \$0.10/GB RAM/hour                                      | [→](/docs/core-concepts/scaling/container-profiles)                                             |
| Memory Optimized (R) Containers | \$0.05/GB RAM/hour                                      | [→](/docs/core-concepts/scaling/container-profiles)                                             |
| **Databases**                   |                                                         |                                                                                            |
| Database Storage (Disk)         | \$0.20/GB/month                                         | [→](/docs/core-concepts/scaling/database-scaling)                                               |
| Database IOPS                   | \$0.01/IOPS after the first 3,000 IOPs/month (included) | [→](/docs/core-concepts/scaling/database-scaling)                                               |
| Database Backups                | \$0.02/GB/month                                         | [→](/docs/core-concepts/managed-databases/managing-databases/database-backups)                  |
| **Isolation**                   |                                                         |                                                                                            |
| Shared Stack                    | Free                                                    | [→](/docs/core-concepts/architecture/stacks)                                                    |
| Dedicated Stack                 | \$499/Stack/month                                       | [→](/docs/core-concepts/architecture/stacks)                                                    |
| **Connectivity**                |                                                         | [→]()                                                                                      |
| Endpoints (Load Balancers)      | \$0.06/endpoint/hour                                    | [→](/docs/core-concepts/apps/connecting-to-apps/app-endpoints/overview#types-of-app-endpoints)  |
| Shared HTTP(S) Endpoints        | \$0.04/endpoint/hour                                    | [→](/docs/core-concepts/apps/connecting-to-apps/app-endpoints/https-endpoints/shared-endpoints) |
| VPN                             | \$99/VPN peer/month                                     | [→](/docs/core-concepts/integrations/network-integrations)                                      |
| **Security & Compliance**       |                                                         |                                                                                            |
| HIDS Reporting                  | [Contact us]()                                          | [→](/docs/core-concepts/security-compliance/hids)                                               |

### Enterprise and Volume Pricing

Aptible offers discounts for Enterprise and volume agreements. All agreements require a 12-month commitment. [Contact us to request a quote.](https://app.aptible.com/contact)

# Self Hosted Pricing

<Info>
  This offering is currently in limited release. [Request early access here](https://app.aptible.com/signup?cta=early-access).
</Info>

The Self Hosted offering allows companies to host the Aptible platform directly within their own AWS accounts. This is ideal for organizations that already existing AWS usage or organizations interested in host their own infrastructure. With this offering, you pay Aptible a platform fee, and your infrastructure costs are paid directly to AWS.

<CardGroup>
  <Card title="Unified Infrastructure" icon="badge-check">
    Manage your AWS infrastructure in your own account
  </Card>

  <Card title="Infrastructure costs paid directly to AWS" icon="aws">
    Leverage AWS discount and credit programs
  </Card>

  <Card title="Full access to AWS tools" icon="unlock">
    Unlock full access to tools and services within AWS marketplace
  </Card>
</CardGroup>

### On-Demand and Enterprise Pricing

All pricing for our Self Hosted offering is custom. This allows us to tailor agreements designed for organizations of all sizes.

# Support Plans

All Aptible customers receive access to email support with our Customer Reliability team. Our support plans give you additional access to things like increased targetted response times, 24x7 urgent support, Slack support, and a designated technical resources from the Aptible team.

<CardGroup>
  <Card title="Standard" icon="signal-fair">
    **\$0/mo**

    Standard support with our technical experts. Recommended for the average production workload.
  </Card>

  <Card title="Premium" icon="signal-good">
    **\$499/mo**

    Faster response times with our technical experts. Recommended for average production workloads, with escalation ability.
  </Card>

  <Card title="Enterprise" icon="signal-strong">
    **Custom**

    Dedicated team of technical experts. Recommended for critical production workloads that require 24x7 support. Includes a Technical Account Manager and Slack support.
  </Card>
</CardGroup>

|                                | Standard        | Premium                                       | Enterprise                                    |
| ------------------------------ | --------------- | --------------------------------------------- | --------------------------------------------- |
| Get Started                    | Included        | [Contact us](https://app.aptible.com/contact) | [Contact us](https://app.aptible.com/contact) |
| **Target Response Time**       |                 |                                               |                                               |
| Low Priority                   | 2 Business Days | 2 Business Days                               | 2 Business Days                               |
| Normal Priority                | 1 Business Day  | 1 Business Day                                | 1 Business Day                                |
| High Priority                  | 1 Business Day  | 3 Business Hours                              | 3 Business Hours                              |
| Urgent Priority                | 1 Business Day  | 3 Business Hours                              | 1 Calendar Hour                               |
| **Support Options**            |                 |                                               |                                               |
| Email and Zendesk Support      | ✔️              | ✔️                                            | ✔️                                            |
| Slack Support (for Low/Normal) | -               | -                                             | ✔️                                            |
| 24/7 Support (for Urgent)      | -               | -                                             | ✔️                                            |
| Production Readiness Reviews   | -               | -                                             | ✔️                                            |
| Architectural Reviews          | -               | -                                             | ✔️                                            |
| Technical Account Manager      | -               | -                                             | ✔️                                            |

<Note>
  Aptible is committed to best-in-class uptime for all customers regardless of support plan. Aptible will make reasonable efforts to ensure your services running in Dedicated Environments are available with a Monthly Uptime Percentage of at least 99.95%. This means that we guarantee our customers will experience no more than 21.56 min/month of Unavailability.\
  Unavailability, for app services and databases, is when our customer's service or database is not running or not reachable due to Aptible's fault. Details on our commitment to uptime and company level SLAs can be found [here](https://www.aptible.com/legal/service-level-agreement). The following Support plans and their associated target response times are for roadblocks that customers may run into while Aptible Services are up and running as expected.
</Note>

# Trials

Aptible offers a 30-day free trial for Aptible-hosted resources upon sign-up if you sign up with a business email.

<Tip>
  Didn't receive a trial by default? [Contact us!](https://www.aptible.com/contact)
</Tip>

### Trial Usage Limits

All accounts on a trial have the following usage limits in place:

* **Scaling Limits**: 3GB of Compute, 20GB of Storage, 1 Endpoint
* **Stacks Limits:** Deploy to Shared Stacks in US East

Ready to scale beyond the trial? [Upgrade your plan to the Development or Production plan here](https://app.aptible.com/plans) in the Plans page to scale unlimitedly.

# FAQ

<AccordionGroup>
  <Accordion title="What’s the difference between the Aptible Hosted and Self Hosted options?">
    Hundreds of the fastest growing startups and scaling companies have used **Aptible’s hosted platform** for a decade. In this option, Aptible hosts and manages your resources, abstracting away all the complexity of interacting with an underlying cloud provider and ensuring resources are provisioned properly.

    Aptible also manages **existing resources hosted in your own cloud account**. This means that you integrate Aptible with your cloud accounts and Aptible helps your platform engineering team create a platform on top of the infrastructure you already have. In this option, you control and pay for your own cloud accounts, while Aptible helps you analyze and standardize your cloud resources.
  </Accordion>

  <Accordion title="How can I upgrade my support plan?">
    [Contact us](https://app.aptible.com/contact) to ugprade your support plan.
  </Accordion>

  <Accordion title="How do I manage billing details such as payment information or invoices?">
    See our [Billing & Payments](/docs/core-concepts/billing-payments) page for more information.
  </Accordion>

  <Accordion title="Does Aptible offer a startup program?">
    Yes, see our [Startup Program page for more information](https://www.aptible.com/startup).
  </Accordion>
</AccordionGroup>


# Terraform
Source: https://www.aptible.com/docs/reference/terraform

Learn to manage Aptible resources directly from Terraform

<Card title="Aptible Terraform Provider" icon={<svg fill="#E09600" width="30px" height="30px"  viewBox="0 0 16 16" xmlns="http://www.w3.org/2000/svg" fill="none">  <g fill="#E09600">  <path d="M1 0v5.05l4.349 2.527V2.526L1 0zM10.175 5.344l-4.35-2.525v5.05l4.35 2.527V5.344zM10.651 10.396V5.344L15 2.819v5.05l-4.349 2.527zM10.174 16l-4.349-2.526v-5.05l4.349 2.525V16z"/>  </g>  </svg>} href="https://registry.terraform.io/providers/aptible/aptible/latest/docs" />

## Overview

The [Aptible Terraform provider](https://registry.terraform.io/providers/aptible/aptible) allows you to manage your Aptible resources directly from Terraform - enabling infrastructure as code (IaC) instead of manually initiating Operations from the Aptible Dashboard of Aptible CLI. You can use the Aptible Terraform to automate the process of setting up new Environments, including:

* Creating, scaling, modifying, and deprovisioning Apps and Databases

* Creating and deprovisioning Log Drains and Metric Drains (including the [Aptible Terraform Metrics Module](https://registry.terraform.io/modules/aptible/metrics/aptible/latest), which provisions built Grafana dashboards with alerting)

* Creating, modifying, and provisioning App Endpoints and Database Endpoints

For an overview of what actions the Aptible Terraform Provider supports, see the [Feature Support Matrix](/docs/reference/interface-feature#feature-support-matrix).

## Using the Aptible Terraform Provider

### Environment definition

The Environment resource is used to create and manage [Environments](https://www.aptible.com/docs/core-concepts/architecture/environments) running on Aptible Deploy.

```hcl theme={null}
data "aptible_stack" "example" {
    name = "example-stack"
}

resource "aptible_environment" "example" {
  stack_id = data.aptible_stack.example.stack_id
  org_id   = data.aptible_stack.example.org_id
  handle   = "example-env"
}
```

### Deployment and managing Docker images

[Deploying via Docker image](/docs/how-to-guides/app-guides/migrate-dockerfile-to-direct-image-deploy) is currently the only deployment method supported with Terraform. If you'd like to use Terraform to deploy your Apps and you're currently deploying via Git, you'll need to switch. See [Migrating from deploying via Git](/docs/how-to-guides/app-guides/migrate-dockerfile-to-direct-image-deploy) for tips on how to do so.

If you're already deploying via Docker image, managing this is pretty easy. The app resource uses three separate attributes:

* `docker_image` - The Docker image to deploy (e.g. `quay.io/aptible/deploy-demo-app`).
* `private_registry_username` - (Optional) Username for authenticating with a private Docker registry.
* `private_registry_password` - (Optional) Password for authenticating with a private Docker registry.

```hcl theme={null}
resource "aptible_app" "example-app" {
    env_id         = data.aptible_environment.example.env_id
    handle         = "example-app"
    docker_image = "quay.io/your-org/your-image"
    // Optional:
    private_registry_username = "registry_username"
    private_registry_password = "registry_password"
}
```

<Note>If you previously configured these settings through `aptible_app.config`, you can remove them from the config</Note>

<Warning> Please ensure you have the correct image, username, and password set every time you run `terraform apply`. If you are deploying outside of Terraform, you will also need to keep your Terraform configuration up to date. See [Terraform's refresh Terraform configuration documentation](https://developer.hashicorp.com/terraform/cli/commands/refresh) for more information.</Warning>

<Tip> For a step-by-step tutorial in deploying a metric drain with Terraform, please visit our [Terraform Metric Drain Deployment Guide](/docs/how-to-guides/app-guides/deploy-metric-drain-with-terraform)</Tip>

## Managing Services

### Managing Services

The service `process_type` should match what's contained in your Procfile. Otherwise, service container sizes and container counts cannot be defined and managed individually. The process\_type maps directly to the Service name used in the Procfile. If you are not using a Procfile, you will have a single Service with the process\_type of cmd.

```hcl theme={null}
resource "aptible_app" "example-app" {
  env_id         = data.aptible_environment.example.env_id
  handle         = "example-app"
  docker_image = "quay.io/your-org/your-image"
  service {
    process_type           = "sidekiq"
    container_count        = 1
    container_memory_limit = 1024
  }
  service {
    process_type           = "web"
    container_count        = 2
    container_memory_limit = 4096
  }
}
```

### Referencing Resources in Configurations

Resources can easily be referenced in configurations when using Terraform. Here is an example of an App configuration that references Databases:

```hcl theme={null}
resource "aptible_app" "example-app" {
    env_id = data.aptible_environment.example.env_id
    handle = "example-app"
    docker_image = "quay.io/your-org/your-image"
    config = {
        "REDIS_URL": aptible_database.example-redis-db.default_connection_url,
        "DATABASE_URL": aptible_database.example-pg-db.default_connection_url,
    }
    service {
        process_type           = "cmd"
        container_count        = 1
        container_memory_limit = 1024
    }
}

resource "aptible_database" "example-redis-b" {
  env_id         = data.aptible_environment.example.env_id
  handle         = "example-redis-db"
  database_type  = "redis"
  container_size = 512
  disk_size      = 10
  version        = "5.0"
}

resource "aptible_database" "example-pg-db" {
  env_id         = data.aptible_environment.example.env_id
  handle         = "example-pg-db"
  database_type  = "postgresql"
  container_size = 1024
  disk_size      = 10
  version        = "12"
}
```

Some apps use the port, hostname, username, and password broken apart rather than as a standalone connection URL. Terraform can break those apart, or you can add some logic in your app or container entry point to achieve this. This also works with endpoints. For example:

```hcl theme={null}
resource "aptible_app" "example-app" {
  env_id = data.aptible_environment.example.env_id
  handle = "example-app"
  docker_image = "quay.io/your-org/your-image"
  config = {
    "ANOTHER_APP_URL": aptible_endpoint.example-endpoint.virtual_domain,
  }
  service {
    process_type = "cmd"
    container_count = 1
    container_memory_limit = 1024
  }
}

resource "aptible_app" "another-app" {
  env_id = data.aptible_environment.example.env_id
  handle = "another-app"
  docker_image = "quay.io/your-org/another-image"
  config = {}
  service {
    process_type = "cmd"
    container_count = 1
    container_memory_limit = 1024
  }
}

resource "aptible_endpoint" "example-endpoint" {
  env_id         = data.aptible_environment.example.env_id
  default_domain = true
  internal       = true
  platform       = "alb"
  process_type   = "cmd"
  endpoint_type  = "https"
  resource_id    = aptible_app.another-app.app_id
  resource_type  = "app"
  ip_filtering   = []
}
```

The value `aptible_endpoint.example-endpoint.virtual_domain` will be the domain used to access the Endpoint (so `app-0000.on-aptible.com` or [`www.example.com`).](https://www.example.com\).)

<Note> If your Endpoint uses a wildcard certificate/domain, `virtual_domain` would be something like `*.example.com` which is not a valid domain name. Therefore, when using a wildcard domain, you should provide the subdomain you want your application to use to access the Endpoint, like `www.example.com`, rather than relying solely on the Endpoint's `virtual_domain`.</Note>

## Circular Dependencies

One potential risk of relying on URLs to be set in App configurations is circular dependencies. This happens when your App uses the Endpoint URL in its configuration, but the Endpoint cannot be created until the App exists. Terraform does not have a graceful way of handling circular dependencies. While this approach won't work for default domains, the easiest option is to define a variable that can be referenced in both the Endpoint resource and the App configuration:

```hcl theme={null}
variable "example_domain" {
  description = "The domain name"
  type        = string
  default     = "www.example.com"
}

resource "aptible_app" "example-app" {
  env_id = data.aptible_environment.example.env_id
  handle = "example-app"
  docker_image = "quay.io/your-org/your-image"
  config = {
    "ANOTHER_APP_URL": var.example_domain,
  }
  service {
    process_type = "cmd"
    container_count = 1
    container_memory_limit = 1024
  }
}

resource "aptible_endpoint" "example-endpoint" {
  env_id         = data.aptible_environment.example.env_id
  endpoint_type  = "https"
  internal       = false
  managed        = true
  platform       = "alb"
  process_type   = "cmd"
  resource_id    = aptible_app.example-app.app_id
  resource_type  = "app"
  domain         = var.example_domain
  ip_filtering   = []
}
```

## Managing DNS

While Aptible does not directly manage your DNS, we do provide you the information you need to manage DNS. For example, if you are using Cloudflare for your DNS, and you have an endpoint called `example-endpoint`, you would be able to create the record:

```hcl theme={null}
resource "cloudflare_record" "example_app_dns" {
  zone_id = cloudflare_zone.example.id
  name    = "www.example"
  type    = "CNAME"
  value   = aptible_endpoint.example-endpoint.id
  ttl     = 60
}
```

And for the Managed HTTPS [dns-01](/docs/core-concepts/apps/connecting-to-apps/app-endpoints/managed-tls#dns-01) verification record:

```hcl theme={null}
resource "cloudflare_record" "example_app_acme" {
  zone_id = cloudflare_zone.example.id
  name    = "_acme-challange.www.example"
  type    = "CNAME"
  value   = "acme.${aptible_endpoint.example-endpoint.id}"
  ttl     = 60
}
```

## Endpoint Settings

You can configure endpoint settings like timeouts, HTTPS redirects, and maintenance pages directly on the `aptible_endpoint` resource using various attributes. See the [App Endpoints documentation](/docs/core-concepts/apps/connecting-to-apps/app-endpoints/overview) for available options by endpoint type.

```hcl theme={null}
resource "aptible_endpoint" "example_endpoint" {
  env_id         = data.aptible_environment.example.env_id
  resource_id    = aptible_app.example.app_id
  resource_type  = "app"
  process_type   = "cmd"
  endpoint_type  = "https"
  default_domain = true
  platform       = "alb"
  idle_timeout                = 120
  force_ssl                   = true
  maintenance_page_url        = "https://example.com/maintenance.html"
  release_healthcheck_timeout = 90
  strict_health_checks        = false
  show_elb_healthchecks       = true
  ssl_protocols_override      = "TLSv1.3"
}
```

<Note>If you previously configured these settings through `aptible_app.config`, move them to `aptible_endpoint` for cleaner resource organization.</Note>

## Secure/Sensitive Values

You can use Terraform to mark values as secure. These values are redacted in the output of `terraform plan` and `terraform apply`.

```hcl theme={null}

variable "shhh" {
  description = "A sensitive value"
  type        = string
  sensitive   = true
}

resource "aptible_app" "example-app" {
  env_id = data.aptible_environment.example.env_id
  handle = "example-app"
  docker_image = "quay.io/your-org/your-image"
  config = {
    "SHHH": var.shhh,
  }
  service {
    process_type = "cmd"
    container_count = 1
    container_memory_limit = 1024
  }
}
```

When you run `terraform state show` these values will also be marked as sensitive. For example:

```hcl theme={null}
resource "aptible_app" "example-app" {
    app_id   = 000000
    config   = {
        "SHHH" = (sensitive)
    }
    env_id   = 4749
    git_repo = "git@beta.aptible.com:terraform-example-environment/example-app.git"
    handle   = "example-app"
    id       = "000000"

    service {
        container_count        = 1
        container_memory_limit = 1024
        process_type           = "cmd"
    }
}
```

## Spinning down Terraform Resources

Resources created using Terraform should not be deleted through the Dashboard or CLI. Deleting through the Dashboard or CLI does not update the Terraform state which will result in errors the next time you run terraform plan or terraform apply. Instead, use terraform plan -destroy to see which resources will be destroyed and then use terraform destroy to destroy those resources.

If a Terraform-created resource is deleted through the Dashboard or CLI, use the terraform state rm [command](https://developer.hashicorp.com/terraform/cli/commands/state/rm) to remove the deleted resource from the Terraform state file. The next time you run terraform apply, the resource will be recreated to reflect the configuration.