Support running PostgREST docker in AWS ECS fargate

[DeboBurro]

Problem

Environment: AWS ECS fargate, awsvpc mode
PostgREST: 13.0.4 ( in docker)

I have a AWS ECS task definition that runs 2 containers at the same time.
Container 1 is an API service uses port 3000 which runs fine.
Container 2 is a PostgREST service that we try to integrate with, uses ports 3091 and 3090.
But whenever I spin up the task in AWS ECS cluster, the PostgREST service container check check shows unhealthy in ECS with exit code 255.

Per log, it shows db connection terminated in the end but I don't think it has anything to do with the health check

25/Aug/2025:21:30:19 +0000: Starting PostgREST 13.0.5...
25/Aug/2025:21:30:19 +0000: Trying to borrow a connection from pool
25/Aug/2025:21:30:19 +0000: Admin server listening on 0.0.0.0:3091
25/Aug/2025:21:30:19 +0000: Connection 4ab70b83-005d-47d4-a8fd-bdc5b2b3a3d5 is being established
25/Aug/2025:21:30:19 +0000: API server listening on 0.0.0.0:3090
25/Aug/2025:21:30:19 +0000: Listening for database notifications on the "pgrst" channel
25/Aug/2025:21:30:19 +0000: Connection 4ab70b83-005d-47d4-a8fd-bdc5b2b3a3d5 is available
25/Aug/2025:21:30:19 +0000: Connection 4ab70b83-005d-47d4-a8fd-bdc5b2b3a3d5 is used
25/Aug/2025:21:30:19 +0000: Connection 4ab70b83-005d-47d4-a8fd-bdc5b2b3a3d5 is available
25/Aug/2025:21:30:19 +0000: Borrowed a connection from the pool
25/Aug/2025:21:30:19 +0000: Successfully connected to PostgreSQL 16.8 on x86_64-pc-linux-gnu, compiled by gcc (GCC) 7.3.1 20180712 (Red Hat 7.3.1-17), 64-bit
25/Aug/2025:21:30:19 +0000: Connection Pool initialized with a maximum size of 10 connections
25/Aug/2025:21:30:19 +0000: Trying to borrow a connection from pool
25/Aug/2025:21:30:19 +0000: Connection 4ab70b83-005d-47d4-a8fd-bdc5b2b3a3d5 is used
25/Aug/2025:21:30:19 +0000: Connection 4ab70b83-005d-47d4-a8fd-bdc5b2b3a3d5 is available
25/Aug/2025:21:30:19 +0000: Borrowed a connection from the pool
25/Aug/2025:21:30:19 +0000: Trying to borrow a connection from pool
25/Aug/2025:21:30:19 +0000: Connection 4ab70b83-005d-47d4-a8fd-bdc5b2b3a3d5 is used
25/Aug/2025:21:30:19 +0000: Connection 4ab70b83-005d-47d4-a8fd-bdc5b2b3a3d5 is available
25/Aug/2025:21:30:19 +0000: Borrowed a connection from the pool
25/Aug/2025:21:30:19 +0000: Config reloaded
25/Aug/2025:21:30:19 +0000: Trying to borrow a connection from pool
25/Aug/2025:21:30:19 +0000: Connection 4ab70b83-005d-47d4-a8fd-bdc5b2b3a3d5 is used
25/Aug/2025:21:30:19 +0000: Connection 4ab70b83-005d-47d4-a8fd-bdc5b2b3a3d5 is available
25/Aug/2025:21:30:19 +0000: Borrowed a connection from the pool
25/Aug/2025:21:30:19 +0000: Schema cache queried in 14.6 milliseconds
25/Aug/2025:21:30:19 +0000: Schema cache loaded 24 Relations, 16 Relationships, 265 Functions, 0 Domain Representations, 4 Media Type Handlers, 597 Timezones
25/Aug/2025:21:30:19 +0000: Schema cache loaded in 0.8 milliseconds
25/Aug/2025:22:00:20 +0000: Connection 4ab70b83-005d-47d4-a8fd-bdc5b2b3a3d5 is terminated due to max lifetime

Here is the example task definition:

{
    "taskDefinitionArn": "arn:aws:ecs:us-west-2:123456789123:task-definition/example-app:143",
    "containerDefinitions": [
        {
            ## Container 1 using port 3000
        },
        {
            ## Container 2 using ports 3090 and 3091
            "name": "postgrest-server",
            "image": "postgrest/postgrest:latest",
            "cpu": 0,
            "portMappings": [
                {
                    "name": "postgrest-server-3090-tcp",
                    "containerPort": 3090,
                    "hostPort": 3090,
                    "protocol": "tcp",
                    "appProtocol": "http"
                },
                {
                    "name": "postgrest-server-admin-3091-tcp",
                    "containerPort": 3091,
                    "hostPort": 3091,
                    "protocol": "tcp",
                    "appProtocol": "http"
                }
            ],
            "essential": true,
            "environment": [
                {
                    "name": "PGRST_DB_SCHEMA",
                    "value": "public"
                },
                {
                    "name": "PGRST_LOG_LEVEL",
                    "value": "debug"
                },
                {
                    "name": "PGRST_DB_ANON_ROLE",
                    "value": "postgrest_anon"
                },
                {
                    "name": "PGRST_ADMIN_SERVER_PORT",
                    "value": "3091"
                },
                {
                    "name": "PGRST_SERVER_PORT",
                    "value": "3090"
                },
                {
                    "name": "PGRST_DB_URI",
                    "value": "postgres://USER:PASSWORD@HOST:5432/DB_NAME?sslmode=require"
                },
                {
                    "name": "PGRST_SERVER_HOST",
                    "value": "0.0.0.0"
                },
                {
                    "name": "PGRST_OPENAPI_SERVER_PROXY_URI",
                    "value": "http://0.0.0.0:3090"
                }
            ],
            "mountPoints": [],
            "volumesFrom": [],
            "logConfiguration": {
                "logDriver": "awslogs",
                "options": {
                    "awslogs-group": "/aws/ecs/postgrest-dev-app",
                    "mode": "non-blocking",
                    "awslogs-create-group": "true",
                    "max-buffer-size": "25m",
                    "awslogs-region": "us-west-2",
                    "awslogs-stream-prefix": "ecs"
                }
            },
            "healthCheck": {
                "command": [
                    "CMD-SHELL",
                    "curl -f http://0.0.0.0:3090 || exit 1"
                ],
                "interval": 30,
                "timeout": 5,
                "retries": 3,
                "startPeriod": 10
            },
            "systemControls": []
        }
    ],
    "family": "example-app",
    "taskRoleArn": "arn:aws:iam::123456789123:role/ecs-execution-role",
    "executionRoleArn": "arn:aws:iam::123456789123:role/ecs-execution-role",
    "networkMode": "awsvpc",
    "revision": 143,
    "volumes": [],
    "status": "ACTIVE",
    "requiresAttributes": [
        {
            "name": "com.amazonaws.ecs.capability.logging-driver.awslogs"
        },
        {
            "name": "ecs.capability.execution-role-awslogs"
        },
        {
            "name": "com.amazonaws.ecs.capability.ecr-auth"
        },
        {
            "name": "com.amazonaws.ecs.capability.docker-remote-api.1.19"
        },
        {
            "name": "com.amazonaws.ecs.capability.docker-remote-api.1.28"
        },
        {
            "name": "com.amazonaws.ecs.capability.task-iam-role"
        },
        {
            "name": "ecs.capability.container-health-check"
        },
        {
            "name": "ecs.capability.execution-role-ecr-pull"
        },
        {
            "name": "com.amazonaws.ecs.capability.docker-remote-api.1.18"
        },
        {
            "name": "ecs.capability.task-eni"
        },
        {
            "name": "com.amazonaws.ecs.capability.docker-remote-api.1.29"
        }
    ],
    "placementConstraints": [],
    "compatibilities": [
        "EC2",
        "FARGATE"
    ],
    "requiresCompatibilities": [
        "FARGATE"
    ],
    "cpu": "2048",
    "memory": "8192",
    "runtimePlatform": {
        "cpuArchitecture": "X86_64",
        "operatingSystemFamily": "LINUX"
    },
    "registeredAt": "2025-08-25T21:28:24.687Z",
    "registeredBy": "arn:aws:iam::123456789123:user/user"
}

Solution

The container health check should succeeds without terminating itself in AWS ECS.

[steve-chavez]

Per log, it shows db connection terminated in the end but I don't think it has anything to do with the health check

That's the debug trace of a feature https://docs.postgrest.org/en/v13/references/connection_pool.html#connection-lifetime.
Looks like you're using log-level=debug, I suggest just using the default log-level to not get confused.

But whenever I spin up the task in AWS ECS cluster, the PostgREST service container check check shows unhealthy in ECS with exit code 255.

I don't see anything wrong with the logs. You're going to have to elaborate what does exit code 255 mean. And check the logs when it happens.

[steve-chavez]

        "healthCheck": {

            "command": [
                "CMD-SHELL",
                "curl -f http://0.0.0.0:3090 || exit 1"
            ],

The above is wrong, you need to target http://localhost:3091/ready per your:

            {

                "name": "PGRST_ADMIN_SERVER_PORT",
                "value": "3091"
            },

See https://docs.postgrest.org/en/v13/references/admin_server.html

[DeboBurro]

changed to 0.0.0.0:3091/ready and localhost:3091/ready still showing unhealthy.
let me check more logs

[DeboBurro]

From the load balancer point of view, using 3091/ready is working thanks!!

but when AWS ECS is running the health check, it executes curl and exit command ( curl -f http://0.0.0.0:3091/ready || exit 1 ) in the postgREST docker container, and because those binaries aren't installed, the health check failed.

Do you have any recommendations for running other commands in the postgREST container as a health check?

[DeboBurro]

oh, from the the discussion, health check is not a plan for the official docker image.

Thanks. I will check how to add it in ourselves and see if it works with ECS

[steve-chavez]

For now you'll have to do that yes, but for next version we'll integrate a health check: #4269

[DeboBurro]

Thanks, I will use the flag when it's released.
currently I have this working.

FROM alpine:3.20
RUN apk add --no-cache curl
COPY postgrest /bin/
CMD ["postgrest"]

[DeboBurro]

Th last piece of making it accessible through application load balancer is

• Create Application load balancer
• Create https / http listener ( if https, we need to create domain name and corresponding certificate )
• Create http target group ( AWS ECS requires http )
• Register target which is our AWS ECS service ENI private IP + port 3090

I an see the system API schema ( https://$DOMAIN_NAME/rpc/* ) now but still cannot see our database schema somehow.