Setting Up Yarkon Using an AMI

The following guide describes how to launch a Yarkon Admin Console EC2 instance starting from an AMI (Amazon Machine Image). An AMI is a pre-configured server available from the AWS Market Place that will allow you a quick and simple setup of the service.

For the server to be fully operational, these steps must be complete:

  1. Launch the instance in EC2. It is a standard Ubuntu based Linux web server, running the Yarkon Admin Console application.
  2. Define the AWS security group to secure the server.
  3. Set up an ELB (Elastic Load Balancer) in front of the server, to handle SSL termination. Note that the setup can be completed without this step, but will require setting up an SSL certificate on the server itself. We found that using an ELB for this purpose reduces the time spent on install and future maintenance of the SSL cert, improves performance of the server, and allows for future scalability. Therefore, we recommend this approach.
  4. Add a DNS record using Route 53 or other DNS registrar. This route can map to any sub-domain you choose under your TLD (Top Level Domain). Note that your end-users will access the Yarkon web client from this URL. For instance, if the URL you set up is https://s3.example.com/, client access will be from https://s3.example.com/yarkon/.
  5. Set up the Yarkon Admin Console application on the new server. This is a simple guided (wizard-like) process. Just make sure the pre-requisites for the server are fully met, see here: Setting up the AWS role and policy required for the Yarkon Admin Console.

You also need to have the following:

  1. Access to an SMTP (Email) server. An email server is needed to communicate new passwords to end-users, and to allow them to self-serve their accounts (reset password etc.). To accomplish that, you would need to provide access to an SMTP end-point that Yarkon Admin Console can use to send outbound email. The SES service is a good choice, but any other email service you use for your business should work just as well.
  2. A valid SSL cert. All internet traffic to the Yarkon server must be routed over HTTPS, to ensure that the connection is secure. For that you need to have an SSL certificate, and be able to install it on either the load balancer (if you use one), or the Yarkon Admin Console server. If you register your domain with AWS, this service is offered free of charge by Amazon.
  3. (optional) In case you want to use Integrated Security, where the user permissions are fully managed in IAM, be able to create users, roles and permissions in IAM. For a document on how to do that, please see setting up an AWS organization.

Launch an Instance

The Yarkon Admin Console application is running on a dedicated web server, to be installed in EC2. Start the process just like setting up any other EC2 server, from an AMI. To start, go to your EC2 Dashboard, click the “Launch Instance” button and locate the AMI from the AWS Marketplace.

The Yarkon AMI is based on a standard, latest available Ubuntu server, with the Yarkon application installed and pre-configured on it.

To get it fully operational in your environment, you’d need to follow some basic (and usually standard) steps, often followed when launching an instance a Unix based AMIs.

The next section describes these steps.

Basic Settings

Go through the next few steps as you do when setting up any EC2 server. As always, the instance type should be chosen based on the expected load. Any of the general purpose instance types should do. We recommend you start with a small one (such as t2.medium) and only scale up if needed. You can always do that later.

The next steps are pretty generic. In the Configure Instance Details step, it is important to set up the correct Role. If you did not create the role yet, you can do it later, but the server will not work without the instance role being set, so you’d have to add the role before trying set up the application. This is because the application uses this role to gain API access to AWS (it does not require you to enter AWS keys). For more about the role, see Setting up the AWS role and policy required for the Yarkon Admin Console.

The storage requirements of the instance are low; we use 20GB as the baseline.

Use the Add Tags step to name the instance and add any tags you use to manage your fleet.

Set up the Security Group

If this is the first time you set up a Yarkon server, you will have to define the security group now.

You can leave the SSH port there, just in case you need direct access to the server. By default, the application is serving content on port 4830. This can be changed, but will require accessing the server directly. Since the recommended set up is using an ELB, you can map this port to the standard https port 433 there, so it is better to leave it as is.

Set up an ELB for HTTPS

It is important to know that an ELB is not required to be able to run the application. It is, however, the method considered “best practice” to serving content over SSL from EC2. The only downside is the added cost of the ELB, though this is probably insignificant for an organization running in AWS (when this guide was written, March 2017, this cost was $22.39 per month). The benefits of using an ELB are:

  • better performance – the termination of SSL traffic is handled by the ELB reducing the load from the server.
  • easier to maintain – you can handle the cert at the ELB level, without having to install it on the server; this is especially handy when the time comes to update the cert.
  • support for scalability – should you decide to use more than one Yarkon server (usually for redundancy), using the AWS ELB is the simplest way to go.
  • the only way to use AWS certs – if you choose to use AWS for your cert authority, you must use an ELB. Generally speaking, this is a good choice as cert authorities often charge hundreds of dollars annually for certs.

If you just want to set up Yarkon quickly skipping the ELB and DNS steps, make sure that port 4830 is open to your current IP in the aforementioned security group, then access the server using http://server-ip/:4830. Note that until you set up HTTPS using either the recommended ELB approach, or by setting it on the instance itself, you will have to access the server using HTTP, which is not secure and therefore not recommended.

To set up an ELB, follow this guide from Amazon: Tutorial: Create a Classic Load Balancer.

When the ELB is ready, set up SSL following this guide: HTTPS Listeners for Your Classic Load Balancer.

Add a DNS Record using R53

Finally, you’d want to create a DNS record for the server, so it can be accessed by your users.

To do that, use the Route 53 service, and follow this guide from Amazon: Configure a Custom Domain Name for Your Classic Load Balancer.

A common choice is to set up a sub-domain under your TLD for the Yarkon server, for instance, yarkon.your-domain-name.com, so to access the Yarkon Admin Console, you’d use the URL https://yarkon.your-domain-name.com.

Note that the end-users will always access the Web client from a URL that is based on this one, and would be (with the aforementioned) https://yarkon.your-domain-name.com/yarkon/.

Yarkon Admin Console setup

The setup of the application is simple. Browse to the server URL you just created in R53 using any web browser (using the aforementioned example, it would be https://yarkon.your-domain-name.com), and follow the steps on screen.

The process consists of the following steps:

  1. Welcome – listing the pre-requisites; all should have been covered by the work already done.
  2. Contact Details – set up the administrator account and provide contact information. A valid email is required so you can get your temporary password. This email address is not shared outside of the Admin Console.
  3. Access Permissions – define the way the server would integrate with your AWS account. Make sure to specify the proper security model: Integrated Security Model is used for IAM integration, and Shared is used when all users should have the same access level. For more see the document Security Models.
  4. S3 Region – define your preferred AWS S3 region. If you don’t have one, go with the US Standard region.
  5. Mail Settings – specify the details of the mail server you are going to use to communicate registration to your end-users. Any standard SMTP server would do, or you can use AWS SES.
  6. Review & Setup – final review and setup.
  7. If all went well, the Login form will be displayed. Look for the email with your temporary password in the inbox you specified.
  8. To complete, you will be required to choose your password.

Account Details

Go through the Welcome screen and click the Next button to proceed. In the Contact Details put in your contact and the email address you’d like to associate with this account. Note that Yarkon uses your email as a uniquely identifying username for logging in to the system. When your user account is created, a temporary password will be generated for you by the system, and will be sent to this email address, so make sure to use a valid one.

AWS Integration

Next, you tell Yarkon how to access your AWS Account.

In the Access Keys form, enter the API Access Keys you created before and downloaded into the CSV file. You can optionally use the Validate button to verify that the access keys you entered could be used by Yarkon. If the keys are invalid for whatever reason, Yarkon will provide feedback to help you resolve the issue.

Choose the Security Model you would like to use. For more details, please review this document.

If you choose the Integrated Security Model, you will have to choose the IAM role you would use for this IAM integration from the drop-down. This should be the role you created for the instance following the document Setup Yarkon Role.

When you are done, move to the next step – S3 Region – and choose from the drop-down the AWS region you use. While the Yarkon client application would work with any region choice you make here, it is preferable to choose the region where most of your buckets are hosted. If you are unsure, use the default which is US Standard.

Review & Setup

The final step of the process is used for verification. Review the details displayed to ensure all are correct. If you want to make changes, you can use the Update button available for each section. When done, click the Done button to have the system proceed to create your administrator user account and set up Yarkon for your AWS account.

The system might take a moment to complete the registration after going through some back-end validation process. After it completes, it will send an email with your login credentials to the address you entered before.

Login & Set password

Use the temporary password sent to you by email to login to Yarkon for the first time. The system will prompt you to replace the automatically generated temporary password with whichever password you choose.

Note that the same password is used to log in to the Yarkon client application.