Setup guide

S3 bucket configuration

BoomBox reads your music directly from an S3 bucket. This guide walks you through creating the bucket, setting the CORS policy, and wiring up credentials — about 10 minutes total.

Create the bucket

In the AWS S3 console, click Create bucket.

Choose a bucket name (e.g. my-boombox-music). Bucket names are globally unique across all AWS accounts.
Select the AWS region closest to where you run BoomBox. Note this value — it goes in STORAGE_REGION.
Uncheck Block all public access so BoomBox can stream audio and cover images directly from S3 in the browser. You'll still control who can write via the IAM policy and which websites can use the bucket via the CORS rules below.
Leave all other settings at their defaults and click Create bucket.

Set the CORS policy

BoomBox's browser client calls S3 directly to list objects and stream audio. Without a CORS policy the browser will block these requests.

Open your bucket, go to the Permissions tab, and scroll to Cross-origin resource sharing (CORS).
Click Edit and paste the policy below.

CORS configuration (JSON)

[
  {
    "AllowedHeaders": ["*"],
    "AllowedMethods": ["GET", "HEAD"],
    "AllowedOrigins": ["*"],
    "MaxAgeSeconds": 3000
  }
]

Why GET and HEAD? GET is used for audio streaming and cover images. HEAD is used by ListObjectsV2 preflight checks. Uploads go through the BoomBox server, not the browser, so PUT is not needed here.

Create IAM credentials

Create a dedicated IAM user with the minimum permissions BoomBox needs. Never use your root account credentials.

Go to IAM → Users and click Create user. Give it a name like boombox-s3.
On the permissions step, choose Attach policies directly → Create policy. Switch to the JSON editor and paste the policy below, replacing YOUR-BUCKET-NAME with your actual bucket name.

IAM policy (JSON)

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "s3:ListBucket"
      ],
      "Resource": "arn:aws:s3:::YOUR-BUCKET-NAME"
    },
    {
      "Effect": "Allow",
      "Action": [
        "s3:GetObject",
        "s3:PutObject",
        "s3:DeleteObject"
      ],
      "Resource": "arn:aws:s3:::YOUR-BUCKET-NAME/*"
    }
  ]
}

Save the policy, attach it to your new user, and finish creating the user.
Open the user, go to Security credentials, and click Create access key. Choose Application running outside AWS.
Copy the Access key ID and Secret access key — you won't be able to see the secret again.

Wire up your .env

Copy .env.sample to .env in the BoomBox project root and fill in the four S3 variables:

.env

AWS_ACCESS_KEY_ID=AKIAIOSFODNN7EXAMPLE
AWS_SECRET_ACCESS_KEY=wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY
STORAGE_REGION=us-east-1
STORAGE_BUCKET=my-boombox-music

STORAGE_REGION — the region you chose in step 01 (e.g. us-east-1, eu-west-2).
STORAGE_BUCKET — the exact bucket name, not the ARN.

BoomBox validates all four variables at startup and exits with a clear error message if any are missing or empty.

You're ready

With the bucket created, CORS set, and credentials in .env, run deno task start and log in at /admin to upload your first album.

← Back to overview View on GitHub