Environment Variables

The following pertains to Yarkon Server and Yarkon Docker only.

On top of the extensive customization options available through the Yarkon Admin Console, you can also control many aspects of the environment using environment variables. Some customizations are only available through environment variables. In case a feature is customizable using both the user interface and an environment variable, the user interface takes precedence.

Using Environment Variables

How you pass in environment variables to Yarkon depends on your specific deployment architecture. The following are common examples:

Standard Yarkon EC2

When you deploy Yarkon from the standard EC2 image in the AWS Marketplace, the instance is using pm2 as its process manager; environment variables are passed to the running server using the configuration file /var/app/current/yarkon-server.pm2.json. In the following example, you can see how to update the database type using this method.

{
    "apps": [{
        "name": "aphek",
        "script": "./aphek",
        "watch": false,
        "env": {
            "PORT": 80,
            "DATABASE_DIALECT": "mysql",
            "DATABASE_HOST": "url.to.database",
            "DATABASE_PORT": 3306,
            "DATABASE_DATABASE": "aphek",
            "DATABASE_USER": "aphek-user",
            "DATABASE_PASSWORD": "password"
        }
    }]
}

Standard Yarkon Docker

When you deploy Yarkon from the standard docker image in DockerHub, pass in the environment variables same way you manage other variables. 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:

Command line

When running Yarkon directly from the command line, environment variables are set just like you always do with a Unix server, depending on your shell. For instance, when using bash, make sure to export the values before starting Yarkon:

export AWS_ACCESS_KEY_ID=EXAMPLERFP4S3EXAMPLE

Available Variables

The following is an exhaustive list of all environment variables that are currently available with Yarkon, broken down by sections.

Credentials

Yarkon gets its credentials from the environment. The recommended way to facilitate that is to run Yarkon in an EC2 with a machine role. If however you prefer to pass credentials to the instance directly, you can do so using environment variables.

Variable Value Usage Comments
AWS_ACCESS_KEY_ID Access key ID to be used.
AWS_SECRET_ACCESS_KEY Secret access key to be used.
AWS_REGION AWS region to be used.
AWS_ROLE_ARN The role ARN to be used. Integrated Security only.
AWS_ROLE_NAME The role name to be used. Used for display purposes only, but must be specified if AWS_ROLE_ARN is used. Integrated Security only.
AWS_WEB_IDENTITY_TOKEN_FILE The full path for where the token file is. Use this option in case you want to pass credentials to Yarkon using OIDC credentials. Make sure that Yarkon has read access to the file.
Integrated Security only.

Logging

Do not use any of these additional logging options in a production system once your troubleshooting is done, as it might result in large log files and expose some user identifying information.

Yarkon provide extensive logging capabilities out of the box, which are useful for troubleshooting an monitoring. In case you need to debug a specific problem, and require additional logging information, you can add it using any of the following variables.

Variable Value Usage Comments
LOG_PATH Any valid path. Default is "./log/" Override if you want to send the Yarkon log file to a different location. Make sure that Yarkon has write access to the folder you specify, and that the folder exists.
LOG_REQUESTS
  • 0 (or not set) - do not log
  • 1 - basic logging
  • 2 - verbose logging
Log all network (http) requests made by Yarkon Note that this logging option can result in large log files.
LOG_AWS Not set by default Set this variable to "true" to log all requests made to AWS, and responses received. Useful to see what actual information is exchanged with AWS, including timing and retrying details.
LOG_SSO Not set by default Set this variable to "true" to log all requests made to your single sign on provider, and responses received. Useful when troubleshooting SSO related issues.
Use with extreme caution!
LOG_PROXY Not set by default Set this variable to "true" to log all requests made to AWS when a proxy is set. This setting will expose all requests made by end users.
Use with extreme caution!
NO_LOG Not set by default Set this variable to "true" to block all logging. Useful when you want to turn off all logging.

AWS

Variable Value Usage Comments
LIST_BUCKETS An comma delimited list of bucket names. Example: "my_bucket_1,my_bucket_2". Use in case you cannot allow the Yarkon Server the "s3:ListAllMyBuckets" permission, or in case you have a short predefined list of buckets that you want to use with Yarkon. When specified, Yarkon will use this bucket list. It won't attempt to list any other bucket.
INLINE_POLICIES Set to "true" to force Yarkon to inline policies. By default, Yarkon does not inline policies. This usually results in better performance and support for larger more complex policies. If you are making use of conditional policies (ie, with "{aws:username}"), this flag is required. Integrated Security only.
OPT_POLICY Set to "true" to force Yarkon to optimize S3 policies. By default, Yarkon only optimizes policies when they are too large to be used with AWS. Use it in case you get errors referring to policy size too large. In some cases, the AWS policy size tool is incorrect, and a policy that should fit actually does not. In these rare cases, this flag might provide a workaround.
AWS_S3_PATH_STYLE Set to "true". Not set by default. Use this flag to force the server to use the obsolete "path style" bucket addressing. Not recommended. Only needed in case you have old buckets that are named incompatibly with the new naming convention.

License

Yarkon requires a license key to operate. A key is preinstalled with each valid deployment oif Yarkon. In case you need to move the license key to a different location, you can do so.

Variable Value Usage Comments
LICENSE_PATH Any valid path. Default is "./.lic/" Override in case you want to install the license file in a different location. Useful when you need to share a license file between instances.

Database

By default, Yarkon uses its on-board SQLite database to maintain its settings and other important run time information. You can change this configuration to better fit your use case, most notable for the High Availability scenario.

Variable Value Usage Comments
DATABASE_DIALECT
  • MySQL
  • MariaDB
  • SQLite (default)
  • PostgreSQL
  • MSSQL
Override the database dialect to match the one you have. To create the database schema, check out this article.
DATABASE_HOST Full network path to access your database host. This is usually an FQDN URL for your database server.
DATABASE_PORT The network port used by your database. Default is 3306.
DATABASE_DATABASE Database/schema name. Default is "aphek". Override in case you want to change the database name, or run more than one in the same RDS instance.
DATABASE_USER The database username to be used. Make sure that the user has write permissions to the tables.
DATABASE_PASSWORD Password for the aforementioned user.

Connection

Variable Value Usage Comments
PORT The port you want Yarkon to serve on. Default is 4830. Useful when you want to change the Yarkon port, or you want to run more than one instance on the same server. The standard Yarkon AMI uses this variable to run the server on port 80.
SERVER_ROOT The default is "/" (the root of the service). Override it in case you want to serve the server assets from a different location. The common use case is serving the server assets from a CDN.
CLIENT_ROOT The default is "/yarkon". Override it in case you want to serve the client assets from a different location. The common use case is serving the client assets from a CDN.
PROXY_CLIENT_ROOT The default is "/yarkon". Override it in case you want to serve the client assets from a different location. The common use case is serving the client assets from a deployment that requires a proxy with a URL different than the default one.
TLS_KEY Path of the TLS key file. Use when you deploy Yarkon with TLS (https) termination on the instance (not recommended). Must be defined if TLS_CERT is used.
TLS_CERT Path of the TLS cert file. Use when you deploy Yarkon with TLS (https) termination on the instance (not recommended). Must be defined if TLS_KEY is used.

Audit Trail

Yarkon offers a powerful audit trail feature, allowing the admin to monitor user activity. BNy default, the audit trail would use the same credentials handed off to the server, but you can override it here to be able to send the audit trail to another account, or use a credential set with different permissions just for the audit trail CloudWatch access.

Variable Value Usage Comments
AUDIT_TRAIL_AUTH_ACCESS_KEY_ID Access key ID to be used. Make sure that the credentials give Yarkon write access.
AUDIT_TRAIL_AUTH_SECRET_ACCESS_KEY Secret access key to be used.
AUDIT_TRAIL_AUTH_REGION AWS region to be used.

Compatible Providers

When using a third party compatible provider, environment variables must be used to specify the details of the provider.

Variable Value Usage Comments
PROVIDER_NAME The name of the compatible provider. The default name is "S3 Compatible". This name is shown in the client user interface, above the buckets. You can use this field to show the actual provider name, or any other name that is used by your end users to refer to the storage.
PROVIDER_IMAGE An image representing the provider. Can be any valid https URL, or a data: url representing an image. This image is shown in the client user interface at the top right corner, and in the About modal. You can use this field to show the actual provider brand image, or any other image that is used by your end users to refer to the storage.
PROVIDER_END_POINT The S3 API end point exposed by your compatible provider. Any compatible provider will have an API end point. This field is required.
Wasabi, for instance, uses "s3.wasabisys.com".
PROVIDER_IAM_END_POINT The IAM API end point exposed by your compatible provider. This field is needed only when the IAM end point is not the same as the S3 one. If not specified, the PROVIDER_END_POINT will be used.
Wasabi, for instance, uses "iam.wasabisys.com".
PROVIDER_STS_END_POINT The STS API end point exposed by your compatible provider. This field is needed only when the STS end point is not the same as the S3 one. If not specified, the PROVIDER_END_POINT will be used.
Wasabi, for instance, uses "iam.wasabisys.com" (same as the IAM one).
PROVIDER_PROXY_END_POINT The URL of the proxy. Applicable only when proxy is used (it is set in the Provider settings). Override the default value, which is the Yarkon host. Useful for some on-premise providers, that require access through a proxy because the storage does not have a public API end point.
PROVIDER_MULTI_REGION Set to "false" for providers that do not implement multi-region support. The default is "true". Useful for some compatible providers that do not support multi-region and also do not implement regions in their API. This is used to avoid errors when making a region dependent call to a provider that is not fully S3 compatible.
PROVIDER_ARN_PREFIX The default is "arn:aws", which is the AWS S3 standard prefix. Some compatible providers define their own ARN prefix. Use this field to refer to resources that are identified by ARNs. An example for a compatible provider using its own prefix is Dell ECS, that uses "arn:ecs".
PROVIDER_ARN_POLICY_S3_FULL_ACCESS Default is "{PROVIDER_ARN_PREFIX}:iam::aws:policy/AmazonS3FullAccess" You can use this predefined policy in case your provider supports it, and its ARN does not follow the standard AWS S3 naming convention.
PROVIDER_ARN_POLICY_S3_READ_ONLY_ACCESS Default is "{PROVIDER_ARN_PREFIX}:iam::aws:policy/AmazonS3ReadOnlyAccess" You can use this predefined policy in case your provider supports it, and its ARN does not follow the standard AWS S3 naming convention.
PROVIDER_DATA Used to pass specific required provider data to Yarkon. Most providers do not need that. Contact us for more details.

Client User Interface

The user interface is customizable using themes. Some additional customizations are available through environment variables.

Variable Value Usage Comments
CONTACT_US Any valid email address. The default is "contact@yarkon.idanco.com". Override this value to have your end users contact your help desk instead of Yarkon's.