Developer Guide¶

Pre-requisites¶

Before you start writing code, please read:

1. Coding Conventions
2. Code of Conduct

System requirements¶

1. Gradle 8.1, or higher
2. JDK8, JDK11, JDK17 or JDK21

Finding issues to work on¶

We are using GitHub issue tracker to keep track of issues. The ones which are suitable for contributors to help with are marked with the following labels:

Preparing credentials¶

S3 - Easy¶

The easiest way to get started would be to:

1. Go to the Identity and Access Management (IAM)
2. Go to Users -> Add User:
   • Username: my-s3fs-username (or whatever)
   • Access Type: Programmatic access must be selected!
3. Set Permissions:
   • Select Attach existing policies directly
   • Search for AmazonS3FullAccess and select it.
4. Continue with next steps (apply changes if necessary)
5. At the final step you will receive an Access Key and Secret Access Key - copy those into your amazon-test.properties or export them as S3FS_** env variable name (if running in a container).

S3 - Advanced¶

1. Go to the Identity and Access Management (IAM)
2. Go to Policies:
   • Create a new policy
   • Switch to JSON editor and copy the policy below which will limit the access to only a specific bucket:

     {
       "Version": "2012-10-17",
       "Statement": [
         {
           "Sid": "VisualEditor0",
           "Effect": "Allow",
           "Action": [
             "s3:PutObject",
             "s3:GetObjectAcl",
             "s3:GetObject",
             "s3:DeleteObjectVersion",
             "s3:PutReplicationConfiguration",
             "s3:ListBucket",
             "s3:DeleteObject",
             "s3:GetBucketAcl"
           ],
           "Resource": [
             "arn:aws:s3:::YOUR_BUCKET_NAME",
             "arn:aws:s3:::YOUR_BUCKET_NAME/*"
           ]
         },
         {
           "Sid": "VisualEditor1",
           "Effect": "Allow",
           "Action": "s3:ListAllMyBuckets",
           "Resource": "*"
         }
       ]
     }
     

   • Replace YOUR_BUCKET_NAME with your actual bucket name.
   • Give a name and save (i.e. s3fs-full-access-to-YOUR_BUCKET_NAME)
3. Go to Users -> Add User:
   • Username: my-s3fs-username (or whatever)
   • Access Type: Programmatic access must be selected!
4. Set Permissions:
   • Select Attach existing policies directly
   • Search for s3fs-full-access-to-YOUR_BUCKET_NAME and select it
   • Continue with next steps (apply changes if necessary)
5. At the final step you will receive an Access Key and Secret Access Key - copy those into your amazon-test.properties or export them as S3FS_** env variable name (if running in a container).

Building the code¶

Cloning¶

git clone https://github.com/carlspring/s3fs-nio
cd s3fs-nio

Custom proxy (optional)¶

If you have Nexus/Artifactory running locally you can setup Gradle to use that repository.
Place the following configuration in your ~/.gradle/gradle.properties:

s3fs.proxy.url=https://my.local.domain/path/to/repository

Build¶

Builds the entire code and runs unit and integration tests. It is assumed you already have the amazon-test.properties configuration in place under the src/test/resources or src/testIntegration/resources.

./gradlew build

Run only unit tests¶

./gradlew test

Run only integration tests¶

./gradlew testIntegration

You can also use ./gradlew build -x testIntegration to skip the integration tests.

Run all tests¶

./gradlew check

Gradle build properties¶

The following properties can be set in your ~/.gradle/gradle.properties file to modify the build execution