Yarkon Server
Quick start guide
In the following, we show the quickest way to get started with Yarkon Server. 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.
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": "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/*"
]
}
]
}
The policy explained:
- AllowServerToIterateIAMEntities - allow the Yarkon server to see the IAM entities in the account. Yarkon never makes IAM changes, it only reads.
- AllowServerToAssumeRole - allow the Yarkon server to assume role, so it can get the right permissions.
- 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 role
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"
}
]
}
4. Launch the AMI
Yarkon is available as a public Community AMI from AWS. It comes pre-set with a 30 day free trial for up to 10 users. No registration is required.
Using your AWS Console, go to the EC2 Dashboard, then click the Launch Instance button, and go through the launch form in order:
- Name the instance
yarkon-server-test, or anything else you prefer. - In the search box, type "yarkon", and choose the AMI named "yarkon-server-community-edition" from the "Community AMIs" tab.
- Choose any instance type. To minimize cost, you can even use a
nanoinstance type. - Choose your key pair, just in case you'd need to ssh into the instance later.
- Create a new security group; allow SSH from your own IP only, and HTTP traffic from the internet. Since this is just a trial, you can return to secure your instance later, but you can definitely do it now if you prefer.
- Expand the "Advanced details" section, and set the "IAM instance profile" to be the role we just created,
yarkon-admin-role. - Continue to launch the instance and wait till it is ready.
If you prefer to launch your stack from the Marketplace, you can use the BYOL listing - it is identical to the aforementioned Community AMI.
You can also use any of the available Yarkon AWS Marketplace subscriptions - always start with the Free Trial.
Important: When you deploy Yarkon directly from the AWS Marketplace, it will use a CloudFoundation template to set up the stack automatically. We are aware of an issue with one of the components of the template, resulting in the IAM Trust Policy, to be sometimes generated without all required statements. To correct this issue, once the stack is created, make sure that the IAM role created for the server has the aforementioned trust policy; both statements must be included. If one of them is missing, please add it as documented here.
5. Setup the application
Browse to running EC2 instance to complete the setup. The URL would be http://ip-address, with the ip-address being the public IP of your running EC2.
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.
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.
Next, we need to update the security model in Yarkon, and tell Yarkon which user should belong to which IAM group.
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:
-
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:
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.