# Quick Start

This guide demonstrates the basics of Exoscale's Simple Object Storage (SOS).

With [object storage](https://en.wikipedia.org/wiki/Object_storage), you can
store, distribute and manage large quantities of files (or objects). Example uses range from simple backups to complex media delivery.

You can store
almost anything in SOS: assets, [backups](https://www.exoscale.com/backup/), email attachments, videos, pictures
and anything else you may imagine.

Your data will stay in the zone in which you store it. Exoscale will
never move data on your behalf. For example, if you first upload data to 
Simple Object Storage in Geneva, then your data is kept in Switzerland,
under [Swiss privacy regulations](https://www.fedlex.admin.ch/eli/cc/2022/491/en).
Whichever the initial location, it is replicated in that same location in
at least three physical distinct copies to ensure maximum safety.

All the actions we will demonstrate through the command line can also be performed through our CLI or the Portal, although the real power of SOS is in the tools you script, and in the clients you may use in your application.

## S3 Compatibility

SOS is S3 compatible, so it works with most object storage clients and
provides library access from a host of languages. You can drop in from other
services and you will not be locked in. Most of the time, a
change of API credentials and endpoint allows you to switch to our service.

Here are a few clients and tools that you can use:

* [Exoscale CLI]({{< ref "/tools/command-line-interface/" >}})
* [s3cmd](https://s3tools.org/s3cmd)
* [cyberduck](https://cyberduck.io/)
* [owncloud](https://owncloud.com/)
* [boto](https://docs.pythonboto.org/en/latest/)
* [Minio](https://min.io/)

We will use `s3cmd` in this guide.

## Setup

This guide assumes you never used s3cmd. If you have used s3md, take a look at the `.s3cfg` example below, drop in your Exoscale's API Key and API Secret and you can use SOS.

First, install s3cmd with your favorite package manager:

* Debian/Ubuntu Linux: `apt-get update && apt-get install s3cmd`
* macOS: `brew install s3cmd`

Then create a file named `.s3cfg` in your home directory. Copy and paste the following configuration template:

```bash
[default]
host_base = sos-{zone}.exo.io
host_bucket = %(bucket)s.sos-{zone}.exo.io
access_key = $EXO_SOS_KEY
secret_key = $EXO_SOS_SECRET
use_https = True
```

Replace `{zone}` with the zone your bucket belongs to. For example, for a bucket deployed on the `ch-dk-2` zone:

```bash
host_base = sos-ch-dk-2.exo.io
host_bucket = %(bucket)s.sos-ch-dk-2.exo.io
```

Replace `$EXO_SOS_KEY` and `$EXO_SOS_SECRET` with your API Key and API Secret.
You can choose to use your [User Keys]({{< ref "/product/security/iam/quick-start/#user-keys" >}}) 
or a specific [IAM API key]({{< ref "/product/security/iam/quick-start/#api-keys" >}}).

## Your first Bucket

We need to create a container for all of our objects, which is called a
bucket.

```bash
s3cmd mb s3://my-new-bucket
```

This creates a bucket called my-new-bucket.

Bucket names are **unique across the entire platform.** You may encounter an
error creating `my-new-bucket` if the name is already taken.

Why are bucket names unique? Buckets and their content can be accessed under
`https://sos-ch-dk-2.exo.io/my-new-bucket/` or `https://my-new-bucket.sos-ch-dk-2.exo.io`.
Buckets become subdomains and prefixed URLs under the `sos-ch-dk-2.exo.io` domain, so names have to be unique.

This does not mean objects are publicly
accessible, however. You can define precise access control through 
[IAM Keys]({{< ref "/product/security/iam/quick-start/#user-keys" >}}) or 
[ACLs]({{< ref "/product/storage/object-storage/how-to/acl/" >}}), and uploaded objects are private by default.

You can check your bucket has been created by listing your buckets:

```bash
s3cmd ls
```

## Uploading and downloading assets

Now choose file on your computer and upload it to your bucket:

```bash
s3cmd put picture.jpg s3://my-new-bucket/picture.jpg
```

Check your file was uploaded successfully:

```bash
s3cmd ls s3://my-new-bucket
```

You can also verify the presence of your file in the Portal. Select the `Storage` section from the main navigation on the left. You should see your
`my-new-bucket` listed here. Select the bucket and you will find your file.

You can try to upload more files in the Portal by drag-and-drop.

To get your files:

```bash
s3cmd get s3://my-new-bucket/picture.jpg picture_download.jpg
```

## Getting further

Get further with SOS and the S3 compatibility coverage by going over the 
[overview section]({{< ref "/product/storage/object-storage/overview/" >}})