# cloudron-garage

This is a packaging of the open source S3 object store [garage](https://garagehq.deuxfleurs.fr/) for  [Cloudron](https://www.cloudron.io/).

This is built with Garage v2.1.0.

## using the package

Once installed, Garage... doesn't do much. If you install it at 

```
s3.example.com
```

on your Cloudron, if you try and access the root domain, nothing is there.

```
<Error>
  <Code>AccessDenied</Code>
  <Message>Forbidden: Garage does not support anonymous access yet</Message>
  <Resource>/</Resource>
  <Region>garage</Region>
</Error>
```

This is OK. Most things need to be done via the Terminal on your Garage instance. The following information comes from the [Garage documentation](https://garagehq.deuxfleurs.fr/documentation/quick-start/), and you should spend time there if you want to host your own S3 clone.

### creating a layout

First, you'll need to check your instance's status.

```
garage status
```

You'll get something like

```
==== HEALTHY NODES ====
ID                Hostname                              Address           Tags  Zone  Capacity          DataAvail  Version
55d03cf30e7164dd  f3303a68-1d1f-4fc7-8db7-6cdc28d36c04  172.18.17.8:3901              NO ROLE ASSIGNED             v2.1.0
```

You'll particularly want to note the `ID`.

Now, you need to create a layout:

```
garage layout assign -z <zone-name> -c <size> <node_id>
```

or, concretely:

```
garage layout assign -z home -c 1G 55d03cf30e7164dd
```

This creates a zone named `home`, of size `1G`, and uses the ID for the instance we're running on Cloudron. (I have no idea if these are fragile values and break if you migrate or restore from backup at this point...)

This stages, but does not commit, those values.

```
garage layout show
```

to see the planned changes; it will tell you what to do in order to apply your changes. This is probably (the first time)

```
garage layout apply --version 1
```

### creating a bucket

To create a bucket:

```
garage bucket create www-site
```

This creates a bucket called `www-site`.

```
garage key create www-site-key
```

Creates a key id/secret pair for this bucket.

Then, you have to grant permissions to that bucket with that key. As you can see, this can allow write-only, or read-only keys. (See the docs... write-only might not be possible?)

```
garage bucket allow \
  --read \
  --write \
  --owner \
  www-site \
  --key www-site-key
```

From here, you can use standard S3 tooling (`awscli`, `mc`, CyberDuck, etc.) to interact with your bucket.

### exposing a bucket as a website

If you want to expose a bucket (like `www-site`) as a website, that can be done via the command line:

```
garage bucket website --allow www-site
```

(TODO/FIXME: This does not seem to work yet. Not sure how this plays with Cloudron's domain management.)


## about the package

Garage is written in Rust, and distributed in multiple ways; this package is built using [pre-built binaries from the Garage team](https://garagehq.deuxfleurs.fr/download/). 

### building

To build the package,

```
make build
```

This runs `cloudron build`, and may (on first run) request a path to a registry. You can configure a private registry on your own Cloudron for this purpose.


```
<registry-domain>/<username>/<package-name>
```


You can override the version built by passing the variable `VERSION`:

```
make build VERSION=v2.1.0
```

### installing 

```
make install
``` 

takes two environment variables

```
make install DOMAIN=garage.<domain>
```

The image defaults to `garage:latest`; `DOMAIN` determines where the application is installed on Cloudron. It is probably necessary to pass this. E.g.

```
make install DOMAIN=s3.superdomain.com
```

## uninstalling

```
make uninstall DOMAIN=<domain>
```




The package is built using the binary distribution from 


cloudron install --image <registry-domain>/<user>/com.jadud.garage:20251206-135933-1341d195f

cloudron build
cloudron update --app garage.<domain>

These manual steps are necessary once it is running.

https://garagehq.deuxfleurs.fr/documentation/quick-start/

There is a web interface floating around

https://github.com/khairul169/garage-webui

Not sure who provides it/connection to the project/security. I'd be inclined to leave everything  about this as managed by Cloudron or through the command line, especially if it was bundled as a service that could be used by other applications (as a local S3 object store).

example setup for the minio client, which I had laying around

mc alias set garage "https://garage.<domain>"  "<key-id>" "<secret>" --api S3v4

I was able to transfer a file and `mc ls garage/test-bucket`.