# Connecting to the Private Supabase EC2 via AWS SSM

How to reach the **private** Supabase EC2 instance (no public IP, no direct SSH) using **AWS Systems Manager (SSM) Session Manager** — for both an interactive shell and browser access to Supabase Studio via port forwarding.

> The instance is in a private subnet. You **cannot** SSH to it from your laptop. Use SSM instead.

## Production values (Datafy)

| Setting | Value |
|---------|-------|
| EC2 instance ID | `i-03d70f4349cdb8b93` |
| Region | `eu-west-1` (Ireland) |
| Account | `926753675240` |
| Studio/API via Kong | port `8000` on the instance |
| Public URL (via ALB) | `https://supabase.datafy.co.za` |

---

## Two ways to connect

| Goal | Use |
|------|-----|
| Run shell commands on the instance | [Interactive SSM session](#interactive-session) |
| Open Supabase Studio in your browser | [SSM port forwarding](#port-forwarding) |
| View Auth (GoTrue) container logs | After SSM shell: `docs/supabase-auth-container-logs.md` |
| Normal day-to-day Studio access | The ALB URL `https://supabase.datafy.co.za` (no SSM needed) |

---

## Prerequisites

These must be true for SSM to work:

### On the EC2 instance
- **SSM Agent** installed and running (pre-installed on Ubuntu/Amazon Linux AMIs)
- IAM instance role includes **`AmazonSSMManagedInstanceCore`**
- Network path to SSM endpoints — either a **NAT gateway** (outbound 443) or **VPC interface endpoints** for `ssm`, `ssmmessages`, `ec2messages`

### On your local PC
- **AWS CLI v2**
  ```powershell
  aws --version
  ```
- **Session Manager plugin** (separate install from AWS CLI)
  - [Install guide](https://docs.aws.amazon.com/systems-manager/latest/userguide/session-manager-working-with-install-plugin.html)
  ```powershell
  session-manager-plugin
  ```
- AWS credentials / profile configured (see below)

> **Do NOT run these commands in AWS CloudShell.** CloudShell runs inside AWS, so `localPortNumber` opens a port on the CloudShell container — not your PC — and your browser can't reach it. Port forwarding must run from your **local machine**.

---

## AWS profile setup

Find your profile:

```powershell
aws configure list-profiles
```

Confirm it works and points at the right account (`926753675240`):

```powershell
aws sts get-caller-identity --profile <your-profile> --region eu-west-1
```

If you use AWS SSO, log in first:

```powershell
aws sso login --profile <your-profile>
```

You can pass the profile two ways:

```powershell
# Per command
--profile <your-profile>

# Or for the whole shell session
$env:AWS_PROFILE = "<your-profile>"
```

---

<a id="interactive-session"></a>

## Option 1 — Interactive shell session

Opens a terminal on the instance (as `ssm-user`):

```powershell
aws ssm start-session `
  --profile <your-profile> `
  --target i-03d70f4349cdb8b93 `
  --region eu-west-1
```

Once connected, switch to the app user / project directory as needed:

```bash
sudo su - ubuntu
cd ~/supabase-project
docker compose ps
```

Exit with:

```bash
exit
```

---

<a id="port-forwarding"></a>

## Option 2 — Port forwarding (browser access to Studio)

Forwards **local** port `8000` → instance port `8000` (Kong, which serves Studio and the API).

```powershell
aws ssm start-session `
  --profile <your-profile> `
  --target i-03d70f4349cdb8b93 `
  --region eu-west-1 `
  --document-name AWS-StartPortForwardingSession `
  --parameters '{\"portNumber\":[\"8000\"],\"localPortNumber\":[\"8000\"]}'
```

When you see:

```
Waiting for connections...
```

…the tunnel is open. **Leave this window running**, then open in your browser:

```
http://localhost:8000/
```

Log in with the Studio basic-auth credentials from `~/supabase-project/.env`:

```env
DASHBOARD_USERNAME=admin
DASHBOARD_PASSWORD=<your-strong-password>
```

Stop the tunnel with `Ctrl+C` when finished.

> `Waiting for connections...` is the **normal idle state** — it is not an error. It simply means nothing has connected to local port `8000` yet.

### Forward a different local port

If local `8000` is already in use, map to another local port (e.g. `8001`):

```powershell
aws ssm start-session `
  --profile <your-profile> `
  --target i-03d70f4349cdb8b93 `
  --region eu-west-1 `
  --document-name AWS-StartPortForwardingSession `
  --parameters '{\"portNumber\":[\"8000\"],\"localPortNumber\":[\"8001\"]}'
```

Then browse `http://localhost:8001/`.

### Reach the database through the instance (advanced)

To use a local DB tool against RDS Proxy, forward to the **remote proxy host** through the instance:

```powershell
aws ssm start-session `
  --profile <your-profile> `
  --target i-03d70f4349cdb8b93 `
  --region eu-west-1 `
  --document-name AWS-StartPortForwardingSessionToRemoteHost `
  --parameters '{\"host\":[\"datafy-prod-rds-proxy.proxy-c7aqcoiku4hr.eu-west-1.rds.amazonaws.com\"],\"portNumber\":[\"5432\"],\"localPortNumber\":[\"5432\"]}'
```

Then connect a local client to `localhost:5432` (still `sslmode=require`, fetch the password from Secrets Manager — see `supabase-aws-rds-proxy-setup.md`).

---

## Quick reference

```powershell
# Shell
aws ssm start-session --profile <p> --target i-03d70f4349cdb8b93 --region eu-west-1

# Studio (port forward) — then open http://localhost:8000/
aws ssm start-session --profile <p> --target i-03d70f4349cdb8b93 --region eu-west-1 `
  --document-name AWS-StartPortForwardingSession `
  --parameters '{\"portNumber\":[\"8000\"],\"localPortNumber\":[\"8000\"]}'
```

---

## Troubleshooting

| Symptom | Likely cause | Fix |
|---------|--------------|-----|
| `Waiting for connections...` and browser can't connect | Running in **CloudShell**, not local PC | Run from your local machine with the Session Manager plugin |
| `SessionManagerPlugin is not found` | Plugin not installed | Install the [Session Manager plugin](https://docs.aws.amazon.com/systems-manager/latest/userguide/session-manager-working-with-install-plugin.html) |
| `TargetNotConnected` | SSM Agent not running or no network path | Check agent, instance IAM role, NAT/VPC endpoints |
| `An error occurred (AccessDeniedException)` | Profile lacks `ssm:StartSession` | Add SSM permissions to your IAM user/role |
| `is not authorized to perform: ssm:StartSession on ... document` | Missing permission on the SSM document | Allow `AWS-StartPortForwardingSession` document in IAM policy |
| Instance not listed in Session Manager | Agent/role/network issue | Systems Manager → Fleet Manager should list the instance as managed |
| `localPortNumber` already in use | Another process on local 8000 | Use a different `localPortNumber` (e.g. 8001) |
| Profile points at wrong account | Wrong/expired credentials | `aws sts get-caller-identity`; re-run `aws sso login` if using SSO |

---

## Notes

- **Day-to-day access** to Studio should be via the ALB URL `https://supabase.datafy.co.za` — SSM is for admin/debug or pre-DNS testing.
- Studio (`:3000`) has **no auth on its own**; Kong (`:8000`) adds the dashboard basic auth. Always go through `:8000`, not `:3000`.
- SSM sessions are logged and controlled via IAM — preferable to opening SSH/bastion access on a private instance.