Projects on AWS S3

Crystal has special support for opening projects hosted on AWS S3. This can be useful if you have large *.crystalproj projects that you want to archive in cloud storage while still being able to browse them with Crystal.

Projects opened from S3 are always opened in read-only mode.

Setup

1. Upload your project to S3

Upload your *.crystalproj directory to an S3 bucket, preserving its directory structure. You can use the AWS CLI, the AWS Console, or any S3-compatible upload tool.

For example, if your project is at ~/Website Backups/MySite.crystalproj/, you might upload it to:

s3://my-bucket/Website Backups/MySite.crystalproj/

2. Create or choose an IAM user

You need AWS credentials with permission to read objects from your S3 bucket.

Option A: Use your own IAM user account. If you already use the AWS CLI, your existing credentials likely have sufficient permissions.

Option B: Create a dedicated IAM user with minimal permissions. This is recommended if you want to limit access to only what Crystal needs. Create an IAM user and attach a policy like the following, which grants the minimum permissions needed to read a specific project:

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": [
                "s3:GetObject",
                "s3:HeadObject"
            ],
            "Resource": "arn:aws:s3:::my-bucket/Website Backups/MySite.crystalproj/*"
        }
    ]
}

Replace my-bucket and the path with your actual bucket name and project path.

3. Create an Access Key

If your IAM user does not already have an Access Key, create one in the AWS Console under IAM > Users > (your user) > Security credentials > Access keys. Save the Access Key ID and Secret Access Key. You will need both.

Running Crystal with an S3 project

Using the AWS CLI (recommended)

The simplest approach is to save your credentials using the AWS CLI tool, which Crystal can read automatically.

If you are using your regular IAM user account, run:

$ aws configure

This saves your Access Key ID and Secret Access Key to your default AWS profile. Then open your project with:

$ crystal --readonly s3://my-bucket/Website Backups/MySite.crystalproj/

If you are using a dedicated IAM user, save the credentials to a named profile:

$ aws configure --profile=crystal_s3_readonly

Then set the AWS_PROFILE environment variable when running Crystal:

$ AWS_PROFILE=crystal_s3_readonly crystal --readonly s3://my-bucket/Website Backups/MySite.crystalproj/

Using environment variables

You can pass credentials explicitly through environment variables:

$ export AWS_ACCESS_KEY_ID=AKIA...
$ export AWS_SECRET_ACCESS_KEY=...
$ crystal --readonly "s3://my-bucket/Website Backups/MySite.crystalproj/"

Embedding credentials in the URL

You can also include credentials directly in the S3 URL. This is convenient for one-off use but be careful not to expose credentials in shell history or scripts:

$ crystal --readonly "s3://$AWS_ACCESS_KEY_ID:$AWS_SECRET_ACCESS_KEY@my-bucket/Website Backups/MySite.crystalproj/?region=us-east-2"

The ?region= parameter is recommended when credentials are embedded in the URL. If omitted, the region defaults to us-east-1.

Notes

• Projects on S3 are always opened as read-only. Attempting to open an S3 project as writable will result in an error.
• Crystal downloads the project's entire database file locally when the project is opened. When browsing to individual revisions, only those revisions will be downloaded on demand.