Yarkon Docker

Quick start guide

In the following, we show the quickest way to get started with Yarkon Docker. Once you get Yarkon to work, you can revisit the steps in this quick-start guide, and make the proper adjustments to get the best fit for your particular situation.

For the purpose of this Getting Started guide, we use docker-compose to set up Yarkon on your docker host, but do note that this is just a quick and simple example. To be able to run docker continuously in a production environment, you'd have to set it up properly. If you do choose to use docker-compose, make sure to review the detailed documentation from Docker.

1. Create test S3 buckets

For the purpose of this quick start guide, let's create a couple of test buckets. We want to create two of them, so we can later show you how to control bucket visibility for different users. So head on to your AWS Console and create the two test buckets.

We named our buckets:

• yarkon-quick-start-bucket-a
• yarkon-quick-start-bucket-b

Note that buckets names in S3 are globally unique, so you'd need to come up with your own bucket names. We suggest you'd simply use your company name as a prefix. Later, we will show you how you can use Yarkon to change the display name of your buckets.

2. Add a IAM policy

From the AWS Admin Console, go to the IAM service and create a policy, using the JSON code below for the permissions. Just make sure to replace our sample bucket names with yours. We named the policy yarkon-admin-policy.

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Sid": "AllowServerToIterateBuckets",
            "Effect": "Allow",
            "Action": "s3:ListAllMyBuckets",
            "Resource": "arn:aws:s3:::*"
        }, {
            "Sid": "AllowServerToAccessSpecificBuckets",
            "Effect": "Allow",
            "Action": [
                "s3:ListBucket",
                "s3:GetBucketLocation",
                "s3:GetBucketCORS",
                "s3:PutBucketCORS"
            ],
            "Resource": [
                "arn:aws:s3:::yarkon-quick-start-bucket-a",
                "arn:aws:s3:::yarkon-quick-start-bucket-b"
            ]
        }, {
            "Sid": "AllowUserActionsLimitedToSpecificBuckets",
            "Effect": "Allow",
            "Action": "s3:*",
            "Resource": [
                "arn:aws:s3:::yarkon-quick-start-bucket-a/*",
                "arn:aws:s3:::yarkon-quick-start-bucket-b/*"
            ]
        }
    ]
}

The policy explained:

• AllowServerToIterateBuckets - allow the Yarkon server to see the buckets in the account. If you prefer, you can also specify the buckets.
• AllowServerToAccessSpecificBuckets - allow Yarkon to list the contents of the specific listed bucket. The CORS related permissions are optional, but they make the next steps simpler.
• AllowUserActionsLimitedToSpecificBuckets - allow the user to interact with the bucket. In this Getting Started Guide we give the user full permissions, but we will show you later how to limit that if you want.

3. Add a user

From the AWS Admin Console, using the IAM service, create a user. We named ours yarkon-admin-user. Do not provide this user access to the AWS Management Console. For the user's permissions, directly attach the policy we created in the previous step, named yarkon-admin-policy.

Once the user is created, create an access key. The use case is "Application running on an AWS compute service". Keep the Access key and Secret access key generated, or download the csv file to a safe location.

4. Launch a container

Yarkon is available as a public image from Docker Hub. It comes pre-set with a 30 day free trial for up to 10 users. No registration is required.

The following is a sample docker-compose.yml config file that also shows how to pass in the basic env variables required by Yarkon. Make sure to replace the placeholders with your access key credentials.

version: "3.2"

    # We use "xyz" to denote the version number used. For instance, if you are using
    # yarkon version 4.5.1, "xyz" would be "451". You can use another naming convention
    # if you prefer. Explicitely definding the version number in the image tag and
    # volumes ensures that upgrades can be done sequentially and you can always restore
    # to a previous version.

services:
  server:
    image: "yarkon/server:x.y.z"  # Use the correct tag here, or "latest"
    ports:
      # Map the port of the host to the one used by Yarkon
      - "80:8000"
    environment:
      # When running in AWS, the preferred way to provide AWS API keys to the
      # container is through using an IAM machine role. If this cannot be done,
      # or when running it outside of AWS, you can pass credentials here:
      AWS_ACCESS_KEY_ID: "<access key id>"
      AWS_SECRET_ACCESS_KEY: "<secret access key>"
      AWS_REGION: "us-east-1"

      # The provider name defaults to AWS, but you can change it to something
      # your users might find more recognizable. In the client, it is displayed
      # above the buckets and in the About form.
      PROVIDER_NAME: "My Company"

    volumes:
      - dbdata_xyz:/var/app/current/database
      - yarkon_xyz:/var/app/current/public/yarkon
      - license:/var/app/current/.lic
      - log:/var/app/current/log
volumes:
  dbdata_xyz:
  yarkon_xyz:
  license:
  log:

You can now start the container from the folder where you saved the config file using:

$ docker-compose up

5. Setup the application

Browse to the root of the running container to complete the setup. The URL would be http://domain-name, with the domain-name being the DNS for your docker infrastructure, or its IP address. For instance, when using the aforementioned docker-compose file locally, the set up URL would be http://localhost.

When the one step setup process is done, you should see the the overview page of the Yarkon Admin Console application.

6. Update CORS

Before we can use Yarkon to access S3, we'd need to update CORS for the bucket. For more on CORS and why it is needed, read this guide.

From the Buckets page, select the test buckets you created before, then click the Update CORS button in the toolbar. Review and confirm the change.

7. Log in as a User

Browse to https://app.yarkons3.com/ to log in, using the username and password you created during set up. If all goes well, You should now see the client application, with the two bucket you created, ready for action.

8. Upload a file

To check out Yarkon, upload a test file. Simply click the Upload button, choose any file, and see that it is uploaded. Once the file is successfully uploaded, you can see it in the main view, as well as its content in the preview pane.

You can use Yarkon like any familiar file explorer interface.

9. Add test users

Go back to Yarkon Admin Console, using the URL https://app.yarkons3.com/console/, and add a couple of test users.

From the Users page, click Add and fill in the details. You don't need to use real emails for these test users, but make sure to specify the password so that you can log in as these users in the next steps. We named our test users:

• Yarkon Test A, with the email: yarkon.test.a@yarkons3.com
• Yarkon Test B, with the email: yarkon.test.b@yarkons3.com

Of course, use your domain name instead of yarkons3.com.

Verify that the test users can log in, by browsing to https://app.yarkons3.com/ and using the credentials of one of them. When you log in as a test user, you should be able to see both buckets.

10. Limit access

In most cases, you would want to limit the buckets a user can access. In this tutorial, we will allow the user named Yarkon Test A to access only the bucket yarkon-quick-start-bucket-a, and similarly, the user named Yarkon Test B to access only the bucket yarkon-quick-start-bucket-b.

To make that happen, we need to create a couple of IAM groups, a IAM role, and update the IAM policy.

Head back to the AWS Console, and from the IAM service, create a group named yarkon-group-bucket-a, and use the following policy for it (you can either create the policy and attach it, or inline it in the group):

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Sid": "AllowServerToAccessSpecificBuckets",
            "Effect": "Allow",
            "Action": [
                "s3:ListBucket",
                "s3:GetBucketLocation"
            ],
            "Resource": "arn:aws:s3:::yarkon-quick-start-bucket-a"
        }, {
            "Sid": "AllowUserActionsLimitedToSpecificBuckets",
            "Effect": "Allow",
            "Action": "s3:*",
            "Resource": "arn:aws:s3:::yarkon-quick-start-bucket-a/*"
        }
    ]
}

Repeat the same steps for the other test bucket.

Edit the policy yarkon-admin-policy, adding the required IAM permissions. Use the following JSON, the difference is the two top statements. Make sure to replace the placeholders with your AWS account ID (you can get it from the top level menu).

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Sid": "AllowServerToIterateIAMEntities",
            "Effect": "Allow",
            "Action": [
                "iam:Get*",
                "iam:List*"
            ],
            "Resource": "arn:aws:iam::<aws-account-id>:*"
        }, {
            "Sid": "AllowServerToAssumeRole",
            "Effect": "Allow",
            "Action": "sts:AssumeRole",
            "Resource": "arn:aws:iam::<aws-account-id>:role/yarkon-admin-role"
        }, {
            "Sid": "AllowServerToIterateBuckets",
            "Effect": "Allow",
            "Action": "s3:ListAllMyBuckets",
            "Resource": "arn:aws:s3:::*"
        }, {
            "Sid": "AllowServerToAccessSpecificBuckets",
            "Effect": "Allow",
            "Action": [
                "s3:ListBucket",
                "s3:GetBucketLocation",
                "s3:GetBucketCORS",
                "s3:PutBucketCORS"
            ],
            "Resource": [
                "arn:aws:s3:::yarkon-quick-start-bucket-a",
                "arn:aws:s3:::yarkon-quick-start-bucket-b"
            ]
        }, {
            "Sid": "AllowUserActionsLimitedToSpecificBuckets",
            "Effect": "Allow",
            "Action": "s3:*",
            "Resource": [
                "arn:aws:s3:::yarkon-quick-start-bucket-a/*",
                "arn:aws:s3:::yarkon-quick-start-bucket-b/*"
            ]
        }
    ]
}

Proceed to create the IAM role. The "Trusted entity type" is "AWS account". For the permissions, use the policy we just created, yarkon-admin-policy. Name your role yarkon-admin-role.

The Trust Relationship should be properly generated for you, but make sure that it looks like so:

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Principal": {
                "Service": "ec2.amazonaws.com"
            },
            "Action": "sts:AssumeRole"
        },
        {
            "Effect": "Allow",
            "Principal": {
                "AWS": "arn:aws:iam::<aws-account-number>:root"
            },
            "Action": "sts:AssumeRole"
        }
    ]
}

Next, we need to update the security model in Yarkon, and tell Yarkon which user should belong to which IAM group.

Update the docker-compose.yml file to include the new role. Make sure to replace the account ID placeholder with your AWS account ID (you can get it from the top level menu).

version: "3.2"

    # We use "xyz" to denote the version number used. For instance, if you are using
    # yarkon version 4.5.1, "xyz" would be "451". You can use another naming convention
    # if you prefer. Explicitely definding the version number in the image tag and
    # volumes ensures that upgrades can be done sequentially and you can always restore
    # to a previous version.

services:
  server:
    image: "yarkon/server:x.y.z"  # Use the correct tag here, or "latest"
    ports:
      # Map the port of the host to the one used by Yarkon
      - "80:8000"
    environment:
      # When running in AWS, the preferred way to provide AWS API keys to the
      # container is through using an IAM machine role. If this cannot be done,
      # or when running it outside of AWS, you can pass credentials here:
      AWS_ACCESS_KEY_ID: "<access key id>"
      AWS_SECRET_ACCESS_KEY: "<secret access key>"
      AWS_REGION: "us-east-1"
      AWS_ROLE_NAME: "yarkon-admin-role"
      AWS_ROLE_ARN: "arn:aws:iam::<account id>:role/yarkon-admin-role"

      # The provider name defaults to AWS, but you can change it to something
      # your users might find more recognizable. In the client, it is displayed
      # above the buckets and in the About form.
      PROVIDER_NAME: "My Company"

    volumes:
      - dbdata_xyz:/var/app/current/database
      - yarkon_xyz:/var/app/current/public/yarkon
      - license:/var/app/current/.lic
      - log:/var/app/current/log
volumes:
  dbdata_xyz:
  yarkon_xyz:
  license:
  log:

Go back to Yarkon Admin Console, and open the Administration page, Access tab. Change the Security Model to integrated and verify that the role yarkon-admin-role is shown. Then click the Validate button to make sure all is in order.

Go to the Users page. For the user named Yarkon Test A, click the Edit menu option (you can see it if you click the down arrow Actions button next to the user's name), and in the Details form, choose the IAM type "Group" and pick the group yarkon-group-bucket-a from the drop down list. Save your changes and dismiss the form. You can use the Action menu View Buckets to verify which buckets this user can access. Repeat for the user Yarkon Test B, using the respective IAM group.

Finally, log in to Yarkon as this user - browse to https://app.yarkons3.com/ and use the credentials of Yarkon Test A to login. You should only see the bucket Yarkon Test A.

Mission accomplished.

Next Steps

Now that you have your Yarkon running, you can proceed to check out the following topics:

• Learn more about the basic and advanced features of Yarkon.

• Customize the look and feel of Yarkon to match your brand, and control which Features are available to the end users.

Once you are ready to take it to the next level, read all about Yarkon's Security models and then apply that to address different permission scenarios.

Start with the guide detailing how to update the IAM policies to support more advanced use cases. Then, check out any of the following that might apply to your use case:

• Licensing Service

• Using only specific buckets

• Limiting the permissions of end users

• Group policies for end users

• Folder level permissions

• Shared buckets for B2B

Upgrade from trial

You are done with your evaluation using the 30 day trial license, and you now want to upgrade to the monthly subscription? You can do it directly from the application, or you can purchase a subscription from our website.