Amazon S3, which stands for Amazon Simple Storage Service, is a technology that was introduced by Amazon Web Services for cloud storage that has since been extended more broadly into a standard programming interface.

Our S3 support lets you store credentials for your S3 object storage buckets on your Urbit ship; once you have done so, you will get additional functionality for uploading your own media within Chat and Groups (for avatars).

To enable S3 support on your ship you'll need to first set up a bucket, and then add its credentials to Landscape using either Landscape or the Dojo.

Bucket Setup

We recommend DigitalOcean's Spaces, but any s3 provider that supports signature v2 should work.

The bucket has to be publicly readable, allow CORS from * origins, allow GET and PUT methods, and allow * headers. Specific instructions for DigitalOcean are below.

In DigitalOcean you'll want to log into your existing account or create a new one if you don't already have one. You can use DigitalOcean for your S3 host even if your Urbit planet is hosted elsewhere.

Click the green Create button at the top of the project page, then click Spaces.

Make the following selections:

• Select the datacenter region closest to you
• Restrict File Listing (leave this as the default)
• Choose a unique name (this is your bucket name)
• Select a project (or leave the default if you don't have multiple)

Once you've created your space you'll want to navigate to its settings in DigitalOcean.

Then you'll want to set the CORS Configurations as specified above, this should look like the following image (your endpoint will vary depending upon region). Finally you'll need to create an API key so you can configure your ship to have access to your newly created s3 bucket.

Click API in the bottom left of the DigitalOcean navigation bar on the left side of the webpage.

Generate a new token, you'll need to copy the access key and secret. Don't navigate away from this page as the secret will only be shown when it is initially created.

Now that we have your S3 ready, we can update the information on your ship.

Add your credentials: Landscape

Navigate to your https://<your-ship-url>/~settings#s3, or click your sigil in the upper-right corner of the window and navigate to System Preferences -> Remote Storage.

The Endpoint depends on the region you selected, but can be found in the settings for your space shown in the image above (in that image we're using the San Francisco region).

The Access Key ID and Secret Access Key is the API key we generated. Put each one in the correct field and save.

The S3 Bucket is the name of your digital ocean space. Once you've added that you'll also need to click "Make Active" from the drop down menu.

Once all of that's complete you should be good to go! Test that things are working by attempting to attach or send and image via chat. It should work. You can manage your images by logging into Digital Ocean and looking at the folder in your newly created space. You can use your same space for multiple urbit IDs by creating new API keys. Each ID will create a new directory within that space using its name by default.

To manage your S3 inventory on your urbit, install Silo: web+urbitgraph://~dister-nocsyx-lassul/silo

Add your credentials: Dojo

Alternatively to the instructions above, you can run these dojo commands instead of updating system preferences. If you followed the instructions above you should not do this.

:s3-store|set-endpoint 'endpoint.mys3provider.com'
:: AWS endpoint example: s3-us-west-2.amazonaws.com
:: Digital Ocean endpoint example: sfo2.digitaloceanspaces.com
:s3-store|set-access-key-id 'MYACCESSKEYID'
:s3-store|set-secret-access-key 'MYSECRETACCESSKEY'
:s3-store|set-current-bucket 'yourbucketname'

Done! If you need to peek at s3-store’s state, you can always run :s3-store +dbug (inside Dojo, not web Dojo, unfortunately). You’ll see the additional functionality appear in Groups and Chat.

Hosting your own S3 solution (Advanced)

If you'd prefer to host your own S3-compatible storage solution locally, have a look at Self-hosting S3 Storage with MinIO.