> For the complete documentation index, see [llms.txt](https://docs.zus.network/zus-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.zus.network/zus-docs/system-overview/storage/zs3-server/use-case-fuse-based-s3fs-mountpoint.md).

# Use Case - FUSE-based S3FS Mountpoint

Use S3FS to interact with your bucket with filesystem commands.

S3FS allows you to mount an S3-compatible object storage bucket as a local file system. This enables seamless access to Züs storage for applications such as Docker containers, WordPress, and analytics tools like Grafana.

**Key Features:**

* Mounts S3 buckets as directories on the host system.
* Supports configuration for access keys, permissions, and URL endpoint customization.
* Provides compatibility for Docker volumes and applications.

After deploying your S3 server, you can integrate [S3FS](https://github.com/s3fs-fuse/s3fs-fuse) to be able to use your allocation as a Data Lake, with S3 support for seamless migration, and lower egress cost compared to other providers.

S3FS makes you operate files and directories in S3 bucket like a local file system, which mean that you can use it in pretty much every use case you can use a typical filesystem directory in (logging, database storage, regular file storage, mount directory for docker containers for data storage or logging).

Moreover, if you have an application that depends on filesystem, you can utilize the power of Züs Storage with **zero code change**.

### Mount your bucket to a filesystem directory using S3FS

Here's a step-by-step guide on how you can apply this change:

1. **Register** to [`https://blimp.software`](https://blimp.software/)
2. **Deploy `zs3server`** as mentioned in [this page](broken://pages/QLV0aOGEcmL7Ls2fj7eC). Once deployed, you can find your URL, access key and secret key in the "Use CLI" section in Blimp's S3 operations page, as shown in the image below.

<figure><img src="https://2414485336-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FUGN3Vu2Hi1voQQLrIVGO%2Fuploads%2FW2wn0RmxDAtjbW2hHNhr%2Fimage.png?alt=media&amp;token=61921535-1fe3-4311-85d5-45c53a814b2c" alt=""><figcaption><p>Fig1: URL, secret and access keys in Using CLI section</p></figcaption></figure>

Example of this command (with the credentials part in double square parts)

{% code overflow="wrap" %}

```
curl -X GET [[https://blimpsogec.zus.network]]/minioclient/?action=createBucket&[[accessKey=devyetii&secretAccessKey=Admin@123]]
```

{% endcode %}

In this example:

* **The URL:** `https://blimpsogec.zus.network`
* **The Access Key:** `devyetii`
* **The secret key:** `Admin@123`

3. **Connect to the machine you'll be using to mount S3FS**. This can be your local machine, or any other remote machine that you have. If it's a remote machine, then you can use SSH to connect to it as follows:

```
ssh <user>@<ip>
```

4. **Create a path to mount your S3 directory** using the command below:

```
mkdir -p <directory_path>
```

{% hint style="info" %}
You can create any mounting path. But make sure you remember it as we'll be using it in Step 7.
{% endhint %}

5. **Prepare you environment variables** as follows:

```
export AWS_ACCESS_KEY_ID=<your-access-key-in-step2>
export AWS_SECRET_ACCESS_KEY=<your-secret-key-in-step2>  
```

6. **Create a bucket on your ZS3 server** as follows:

```
aws --endpoint-url https://<zs3server-url-from-step2> s3 mb s3://<bucket-name>        
```

`aws-cli` installation and usage is explained in details [here](https://github.com/0chain/zs3server/?tab=readme-ov-file#test-using-aws-client-aws).

7. **Install S3FS on your machine.** Provided down below are commands to install in on an Ubuntu machine. If you have any other distro of Linux or another OS, you can refer to this [link](https://github.com/s3fs-fuse/s3fs-fuse)

```
   sudo apt update
   sudo apt install s3fs
```

8. **Prepare the password file** that you'll be using with S3FS to mount your bucket on the mount point. Run the following command to write the contents of your password file, which will be stored in `$HOME/.passwd-s3fs`

```
   echo <your-access-key-from-step2>:<your-secret-key-from-step2> > ${HOME}/.passwd-s3fs 
   chmod 600 ${HOME}/.passwd-s3fs
```

You should replace `<your-access-key-from-step2>` and `<your-secret-key-from-step2>` with the corresponding values.

9. **Mount your bucket** to the created directory path using `s3fs` using the command below:

{% code overflow="wrap" %}

```
   s3fs <bucket-name> <mount-directory> -o passwd_file=${HOME}/.passwd-s3fs -o url=<your-zs3server-url-from-step2> -o  use_path_request_style,allow_other,umask=000,complement_stat,nocopyapi,norenameapi
```

{% endcode %}

You should replace the placeholders in the command as follows:

* `<bucket-name>` should be replaced by the bucket name you used to create the bucket in step 6.
* `<mount-directory>` should be replaced by the mount directory you created in step 4.
* `<your-zs3server-url-from-step2>` should be replaced by the URL shown in step2.

{% hint style="info" %}
You can use the command below to unmount the zus-storage from `<directory_path>`:\
`umount -l <directory_path>`
{% endhint %}

10. **Check if your bucket is mounted successfully** to S3FS mount directory as follows:

```
df -ha | grep "s3fs"
```

This command displays the mounting path details.

**If there is no output,** recheck all the steps to ensure they were executed correctly.

11. Once you mount the Zus storage, any created, copied, or deleted files or directories within the mount **will be reflected on your allocation files** in Blimp, and vice versa.

### Usage Examples

After mounting your bucket to the S3FS mountpoint, you can perform any typical file operation on this mount directory, and it will automatically be reflected to your ZS3 bucket, hence your allocation data showed in Blimp.

For example, write a file and save it to the mount directory (assume it's /mnt/s3fs)

```
cat "I use Züs!" > /mnt/s3fs/my-tools.txt
```

To copy a file:

```
cp ~/my-files/an-awesome-file /mnt/s3fs/my-awesome-files
```

To move a file:

```
mv ~/my-files/an-awesome-file /mnt/s3fs/my-awesome-files
```

To delete a file:

```
rm /mnt/s3fs/my-awesome-files
```

### Troubleshooting and checking the logs

If you encountered any issue working with your mountpoint (using Ubuntu), you can check `syslog` as follows:

```
tail -f /var/logs/syslog | grep s3fs
```

You can also enable debug logging on S3FS as follows:

{% code overflow="wrap" %}

```
s3fs mybucket /path/to/mountpoint -o passwd_file=${HOME}/.passwd-s3fs -o dbglevel=info -f -o curldbg
```

{% endcode %}

### Note on using your S3FS directory as the storage directory for Postgres DBs (using Docker)

You can configure your Postgres DB deployment (using Docker) to use the mounted S3FS directory as storage directory for the DB.

If you're using `docker run` to deploy your Postgres DB, attach the S3FS directory as a mount directory to your deployed container as follows:

{% code overflow="wrap" %}

```
docker run [...some options...] -v <path-in-your-s3fs-mount-directory>:/var/lib/postgresql/data [...some other options...] postgres:15
```

{% endcode %}

If you're using `docker-compose` you can configure your Postgres DB service to use the mounted S3FS directory as storage directory for the DB as follows:

```
services:
    ....
    postgres:
        ....
        volumes:
            - <path-in-your-s3fs-mount-directory>:/var/lib/postgresql/data
        ....
```

In both examples, you should replace `<path-in-your-s3fs-mount-directory>` with some path in your S3FS mount directory, for example: `/mnt/s3fs/data/postgres`

### Integration with Docker Compose

The mounted paths will be used in **Docker Compose** files to specify volumes for various components like logs, Grafana, Sharders, Miners, and RocksDB.

**Paths:**

1. **Sharder Blocks**: `/mnt/s3fs/sharder${SHARDER}/data/blocks`
2. **Miner RocksDB**: `/mnt/s3fs/miner${MINER}/data`
3. **Grafana Loki Logs**: `/mnt/s3fs/loki`

**Docker Compose Configuration**

Sample configuration for **Sharder**:

```yaml
volumes:
  - /mnt/s3fs/sharder${SHARDER}/data/blocks:/0chain/data/blocks
```

Sample configuration for **Grafana Loki**:

```yaml
volumes:
  - /mnt/s3fs/loki:/mnt/s3fs/loki
```

Sample configuration for **Miner**:

```yaml
volumes:
  - /mnt/s3fs/miner${MINER}/data:/0chain/data
```

### Use Cases and Applications

#### **Logs and Monitoring**

* **Grafana Loki**: Stores log data in `/mnt/s3fs/loki`. Use this for real-time log analytics.
* **Sharder Logs**: Logs from sharder operations are stored in `/mnt/s3fs/sharder${SHARDER}/log`.

#### **Data Storage for Load Testing**

For load testing Züs components like Sharders, Miners, and Blobbers:

* Configure **RocksDB** for Miners: `/mnt/s3fs/miner${MINER}/data`.
* Configure **Blocks** for Sharders: `/mnt/s3fs/sharder${SHARDER}/data/blocks`.

{% hint style="info" %}

* **Permissions**: Always secure your `.passwd-s3fs` file to avoid exposing access credentials.
* **Mount Optimization**: Use `-o allow_other` and `-o use_path_request_style` for compatibility with Docker containers.
* **Testing**: Regularly verify mounted paths and data accessibility before starting containers.
* **Monitoring**: Use Grafana Loki and other monitoring tools to track resource usage and logs.
  {% endhint %}