isle/docs/operator/contributing-storage.md

# Contributing Storage

This document is for you if your host machine can be reliably be online at all
times and has 1GB or more of unused drive space you'd like to contribute to the
network.

## Edit `daemon.yml`

Open your `/etc/isle/daemon.yml` file in a text editor, and find the
`storage.allocations` section.

Each allocation in the allocations list describes the space being contributed
from a single physical drive. If you only have one drive then you will only need
one allocation listed.

The comments in the file should be self-explanatory, but ask your admin if you
need any clarification.

Here is an example set of allocations for a host which is contributing space
from two separate drives:

```
storage:
  allocations:

    # 1.2 TB are being shared from drive1
    - data_path: /mnt/drive1/isle/data
      meta_path: /mnt/drive1/isle/meta
      capacity: 1200

    # 100 GB are being shared from drive2
    - data_path: /mnt/drive2/isle/data
      meta_path: /mnt/drive2/isle/meta
      capacity: 100
```

## Set Up Your Firewall

See the doc on [Firewalls](./firewalls.md), to be sure that your host's firewall
is properly set up for providing storage.

## Restart the Daemon

With the `daemon.yml` configured, you should restart your `isle daemon`
process.

The `isle daemon` will automatically allow the ports used for your
storage allocations in the vpn firewall.

## Removing Allocations

If you later decide to no longer provide storage simply remove the
`storage.allocations` item from your `/etc/isle/daemon.yml` file and restart the
`isle daemon` process.

Once removed, it is advisable to wait some time before turning off the daemon or
deleting the data from the data and meta directories which were previously
allocated to. This gives other hosts in the network time to offload all data
that yours was previously hosting.

## Further Reading

Isle uses the [garage][garage] project for its storage system. See the
[Managing Garage](managing-garage.md) document for more
information on how to interact directly with the garage instance being run by
isle.

[garage]: https://garagehq.deuxfleurs.fr/documentation/quick-start/
First public commit There has been over 1 year of commit history leading up to this point, but almost all of that has had some kind network configuration or secrets built into the code. As of today all of that has been removed, and the codebase can finally be published! I am keeping a private copy of the previous commit history, though it's unclear if it will ever be able to be published. 2021-04-20 21:31:37 +00:00			`# Contributing Storage`

Have hosts update garage cluster layout to remove other nodes if necessary 2024-11-05 21:31:57 +00:00			`This document is for you if your host machine can be reliably be online at all`
			`times and has 1GB or more of unused drive space you'd like to contribute to the`
			`network.`
First public commit There has been over 1 year of commit history leading up to this point, but almost all of that has had some kind network configuration or secrets built into the code. As of today all of that has been removed, and the codebase can finally be published! I am keeping a private copy of the previous commit history, though it's unclear if it will ever be able to be published. 2021-04-20 21:31:37 +00:00
Add documentation for admin create-network 2022-11-03 14:38:31 +00:00			## Edit `daemon.yml`
First public commit There has been over 1 year of commit history leading up to this point, but almost all of that has had some kind network configuration or secrets built into the code. As of today all of that has been removed, and the codebase can finally be published! I am keeping a private copy of the previous commit history, though it's unclear if it will ever be able to be published. 2021-04-20 21:31:37 +00:00
Update documentation 2024-07-07 11:37:26 +00:00			Open your `/etc/isle/daemon.yml` file in a text editor, and find the
First public commit There has been over 1 year of commit history leading up to this point, but almost all of that has had some kind network configuration or secrets built into the code. As of today all of that has been removed, and the codebase can finally be published! I am keeping a private copy of the previous commit history, though it's unclear if it will ever be able to be published. 2021-04-20 21:31:37 +00:00			`storage.allocations` section.

			`Each allocation in the allocations list describes the space being contributed`
			`from a single physical drive. If you only have one drive then you will only need`
			`one allocation listed.`

			`The comments in the file should be self-explanatory, but ask your admin if you`
			`need any clarification.`

Have hosts update garage cluster layout to remove other nodes if necessary 2024-11-05 21:31:57 +00:00			`Here is an example set of allocations for a host which is contributing space`
First public commit There has been over 1 year of commit history leading up to this point, but almost all of that has had some kind network configuration or secrets built into the code. As of today all of that has been removed, and the codebase can finally be published! I am keeping a private copy of the previous commit history, though it's unclear if it will ever be able to be published. 2021-04-20 21:31:37 +00:00			`from two separate drives:`

			```
			`storage:`
			`allocations:`

			`# 1.2 TB are being shared from drive1`
Perform all in-code renames which don't affect actual functionality 2023-08-05 21:53:17 +00:00			`- data_path: /mnt/drive1/isle/data`
			`meta_path: /mnt/drive1/isle/meta`
First public commit There has been over 1 year of commit history leading up to this point, but almost all of that has had some kind network configuration or secrets built into the code. As of today all of that has been removed, and the codebase can finally be published! I am keeping a private copy of the previous commit history, though it's unclear if it will ever be able to be published. 2021-04-20 21:31:37 +00:00			`capacity: 1200`

Upgrade garage to v1.0.0 This required switching all garage admin API calls to the new v1 versions, and redoing how the global bucket key is created so it is created via the "create key" API call. 2024-06-11 12:54:26 +00:00			`# 100 GB are being shared from drive2`
Perform all in-code renames which don't affect actual functionality 2023-08-05 21:53:17 +00:00			`- data_path: /mnt/drive2/isle/data`
			`meta_path: /mnt/drive2/isle/meta`
First public commit There has been over 1 year of commit history leading up to this point, but almost all of that has had some kind network configuration or secrets built into the code. As of today all of that has been removed, and the codebase can finally be published! I am keeping a private copy of the previous commit history, though it's unclear if it will ever be able to be published. 2021-04-20 21:31:37 +00:00			`capacity: 100`
			```

Add documentation related to firewalls 2022-11-05 16:16:25 +00:00			`## Set Up Your Firewall`

			`See the doc on [Firewalls](./firewalls.md), to be sure that your host's firewall`
			`is properly set up for providing storage.`

First public commit There has been over 1 year of commit history leading up to this point, but almost all of that has had some kind network configuration or secrets built into the code. As of today all of that has been removed, and the codebase can finally be published! I am keeping a private copy of the previous commit history, though it's unclear if it will ever be able to be published. 2021-04-20 21:31:37 +00:00			`## Restart the Daemon`

Perform all in-code renames which don't affect actual functionality 2023-08-05 21:53:17 +00:00			With the `daemon.yml` configured, you should restart your `isle daemon`
First public commit There has been over 1 year of commit history leading up to this point, but almost all of that has had some kind network configuration or secrets built into the code. As of today all of that has been removed, and the codebase can finally be published! I am keeping a private copy of the previous commit history, though it's unclear if it will ever be able to be published. 2021-04-20 21:31:37 +00:00			`process.`

Perform all in-code renames which don't affect actual functionality 2023-08-05 21:53:17 +00:00			The `isle daemon` will automatically allow the ports used for your
Update firewall information in "Contributing Storage" doc 2022-11-03 13:30:54 +00:00			`storage allocations in the vpn firewall.`

Have hosts update garage cluster layout to remove other nodes if necessary 2024-11-05 21:31:57 +00:00			`## Removing Allocations`

			`If you later decide to no longer provide storage simply remove the`
			`storage.allocations` item from your `/etc/isle/daemon.yml` file and restart the
			`isle daemon` process.

			`Once removed, it is advisable to wait some time before turning off the daemon or`
			`deleting the data from the data and meta directories which were previously`
			`allocated to. This gives other hosts in the network time to offload all data`
			`that yours was previously hosting.`

First public commit There has been over 1 year of commit history leading up to this point, but almost all of that has had some kind network configuration or secrets built into the code. As of today all of that has been removed, and the codebase can finally be published! I am keeping a private copy of the previous commit history, though it's unclear if it will ever be able to be published. 2021-04-20 21:31:37 +00:00			`## Further Reading`

Perform all in-code renames which don't affect actual functionality 2023-08-05 21:53:17 +00:00			`Isle uses the [garage][garage] project for its storage system. See the`
First public commit There has been over 1 year of commit history leading up to this point, but almost all of that has had some kind network configuration or secrets built into the code. As of today all of that has been removed, and the codebase can finally be published! I am keeping a private copy of the previous commit history, though it's unclear if it will ever be able to be published. 2021-04-20 21:31:37 +00:00			`[Managing Garage](managing-garage.md) document for more`
			`information on how to interact directly with the garage instance being run by`
Perform all in-code renames which don't affect actual functionality 2023-08-05 21:53:17 +00:00			`isle.`
First public commit There has been over 1 year of commit history leading up to this point, but almost all of that has had some kind network configuration or secrets built into the code. As of today all of that has been removed, and the codebase can finally be published! I am keeping a private copy of the previous commit history, though it's unclear if it will ever be able to be published. 2021-04-20 21:31:37 +00:00
			`[garage]: https://garagehq.deuxfleurs.fr/documentation/quick-start/`