Yarkon Docker

You should always start with the FREE Tier of Yarkon Cloud, so you can experience the product and ensure it is a good fit for your use case.

If you just want to experiment with Yarkon, you can create throw away S3 buckets and IAM entities. Once you are decided, you can easily recreate the required entities in a production system.

Get the image from Docker Hub

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.

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.

The following is a sample docker-compose that also shows how to pass in the basic env variables required by Yarkon:

version: "3"

    # 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:xyz"  # Use the correct tag here
    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: "EXAMPLERFP4S3EXAMPLE"
      AWS_SECRET_ACCESS_KEY: "examplexcRA2gvPBPKAmt95yWIwz/vJIJexample"
      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
      - /var/log:/var/app/current/log # Map the /var/log folder on the host to the log folder
volumes:
  dbdata_xyz:
  yarkon_xyz:
  license:

Create an S3 bucket

You can use any of your existing S3 buckets, or create a new one. In this Getting Started Guide, we create a new bucket, named yarkon-getting-started.

Log in to your AWS account, and using AWS Admin Console, go to the S3 service and create the bucket. If you are using an existing bucket, you can skip this step.

Create an S3 bucket

Add an IAM policy

Yarkon gets its permissions through IAM policies. It will never allow any end user more than the policy allows; since Yarkon only uses the AWS API to communicate with the AWS backend, it can never perform an action not explicitly allowed by the administrator. The administrator has full control over the permissions granted, and the flexibility is similar to what AWS IAM affords.

For this Getting Started Guide, we will create a basic IAM policy, that allows access only to the bucket we just created.

From the AWS Admin Console, go to the IAM service, and create a policy. We named our policy yarkon-getting-started-policy. The simplest way to create the policy is to copy-paste the below JSON code into the editor tab. Just make sure to use your bucket name where specified.

{
    "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:::<your-bucket-name>"
            ]
        },
        {
            "Sid": "AllowUserActionsLimitedToSpecificBuckets",
            "Effect": "Allow",
            "Action": "s3:*",
            "Resource": [
                "arn:aws:s3:::<your-bucket-name>/*"
            ]
        }
    ]
}

The policy explained in brief:

  • AllowServerToIterateBuckets - allow the Yarkon server to see the buckets in the account.
  • AllowServerToAccessSpecificBuckets - allow Yarkon to list the contents of the specific listed bucket. The CORS related permissions are optional, but they make the next step much simpler.
  • AllowUserActionsLimitedToSpecificBuckets - allow the user to interact with the bucket. In this Getting Started Guide we give the user full permissions, but you can limit these here.
Create IAM policy
Add tags
Review and complete

Add a service user

It the very basic setup, Yarkon Cloud gets its access keys through a service user account. A service user account is an IAM user that represents a machine user, and cannot log in.

From the AWS Admin Console, using the IAM service, create the service user. We named ours yarkon-getting-started-user. Make sure to allow it Programmatic Access only. For the permissions, attach the policy we created in the previous step. Add any tags you like and review. When you get to the last step, make sure to keep the auto-generated keys (or download the csv file with the keys).

Add service user
Add service user permissions
Add service user tags
Review service user
Get service user keys

Setup the keys in the ENV

We are done with the AWS prep work. If you use docker-compose, enter the keys you just got in the environment section (see the sample docker-compose file). If you are using a different deployment method for Docker, update the env variables accordingly, making sure to set all three required variables: AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY and AWS_REGION.

In the Administration page, access tab, keep the security model as Shared, we will get to other security models later.

Update CORS for the bucket

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, using the checkbox interface, select the bucket you want to access, then click the Update CORS button in the toolbar. Review and confirm the change. The list of buckets should reflect the change.

Buckets
Update CORS for the bucket
CORS updated for the bucket

Verify and Login

Go back to the Overview page, and verify that all that is displayed is as expected - there should be one user, and one bucket is set up.

The last step is to login to Yarkon like an end user would, using the URL mapped to the container in your docker host. If you are following the docker-compose example here and use your own computer for the setup, this would simply be http://localhost (because we mapped port 80 to the application running). If you have a dedicated docker host, it would be whichever port you mapped to your running Yarkon docker container. You can login as an end user directly from the Overview page, the link is in the Yarkon Client box.

To login, use the username and password you created when you started the set up process. You should now see the client application, with the one bucket we set up for Yarkon, ready for action.

Overview - Set up done
Client login
Client ready

Upload a file

To check out Yarkon, upload a test file. For this Getting Started Guide, we uploaded a small text file. Once the file is successfully uploaded, you can see it in the main view, as well as its content in the preview pane.

Upload a file
File preview

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.
  • Find out how to add users to 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: