s3-share/README.md

A simple server to share objects on an s3 bucket and display them in a nice way.

# Features

- Share any object on an s3 bucket
- Generate short urls for the share
- Simple API to create shares

# Building

Run `make` and the binary together with the web frontend will be in the `build` directory.

# Usage

Run the `s3browser` binary with the `--help` flag to see the available options.
The `public` directory needs to be in the same directory as the binary.

S3Share requires two things:

- a s3 bucket with read access
- a sql database

## Docker

The docker image is available at [Dockerhub](https://hub.docker.com/r/djeeberjr/s3share). There is also a [docker-compose](docker-compose.yml) file that can be used as an example.

# Synopsis

```
s3share 0.1
Usage: s3share --s3-endpoint ENDPOINT --s3-bucket BUCKET --s3-access-key ACCESS_KEY --s3-secret-key SECRET_KEY [--s3-disable-ssl] [--address ADDRESS] --api-username USERNAME --api-password PASSWORD --db DB

Options:
  --s3-endpoint ENDPOINT
                         host[:port] [env: S3_ENDPOINT]
  --s3-bucket BUCKET     bucket to use [env: S3_BUCKET]
  --s3-access-key ACCESS_KEY [env: S3_ACCESS_KEY]
  --s3-secret-key SECRET_KEY [env: S3_SECRET_KEY]
  --s3-disable-ssl [default: false, env: S3_DISABLE_SSL]
  --address ADDRESS      what address to listen on [default: :3000, env: ADDRESS]
  --api-username USERNAME
                         username for API [env: API_USERNAME]
  --api-password PASSWORD
                         password for API [env: API_PASSWORD]
  --db DB                DSN in format: https://github.com/go-sql-driver/mysql#dsn-data-source-name [env: DB_CONNECTION]
  --help, -h             display this help and exit
  --version              display version and exit
```

# API

Use the provided username and password with basic auth.

Shares ids consist of six alphanumeric characters e.g. `jW8ADy`.

- `GET /api/share`: Get a list of all shares
- `GET /api/share/:id`: Get a share by id. Result:
```json
{"slug":"jW8ADy","key":"/myObj.txt"}
```
- `POST /api/share`: Create a new share. Data to send:
```json
{"key":"/myObj.txt"}
```
- `DELETE /api/share/:id`: Delete a share

Other urls are:

- `/:id` to get the default site to display the share.
- `/s/:id` to get the shared file directly.

When you request a shared file directly, you can add anything after a dot behind the id e.g. `/s/jW8ADy.png`.
This is done to make the browser display the file correctly. On the server side, this will be stripped away.

# Tech stack

## Backend 

- Go
- Minio s3 client
- Mux

## Frontend 

- Svelte
- Highlight.js
- Typescript