Functions

Helpful functions you can use to optimize your configuration files.

HCL supports functions that can be used to generate values in the configuration file. The following functions are supported:

num_cpus

Returns the number of CPUs (logical cores) available on the system.

proksi.hcl

# You can use the num_cpus function to set the number of worker threads
# You can also use math expressions like num_cpus() - 2
worker_threads = num_cpus() - 2

logging {
  level = "info"
}
# ... other configuration

env

You can use the env function to retrieve environment variables during the configuration parsing process of Proksi.

This is particularly useful if you have secrets or other type of data that you do not want to be part of your git or repository:

Usage

env(NAME: string) where NAME is an environment variable present during Proksi's run.

worker_threads = env("WORKERS_COUNT")

routes = [
 {
   upstreams = [
     {
       ip = "localhost"
       port = "8009"

       plugins = [
        {
          name = "basic_auth"
          config = {
            user = env("BASIC_AUTH_USER")
            pass = env("BASIC_AUTH_PASS")
          }
        }
       ]
     }
   ]
 }
]

Errors

This function will throw an error if the environment variable is not set.

import

Configuring Proksi in one single file is a no-brainer, but it works well only when you don't have hundreds of upstreams, routes, headers and reusable pieces that you want to commit or have others work on them too.

The import function is a way to help improve your configuration organization in the long term.

Usage

import(RELATIVE_PATH: string) where relative_path is always a path relative to the main configuration file (not relative to other imports).

The reason the piece above is highlighted is because you can use import within imports and at the end what Proksi does is include them all together, so it needs to find them relative to itself.

proksi.hcl

worker_threads = 2

paths {
  lets_encrypt = "./"
}

routes = [
  import("./sites/my-site.com")
]

And then, a ./sites/my-site.com will look like this:

sites/my-site.com

host = "my-site.com"

# downstream headers
headers {
  add = [{
      name = "server"
      value = "cool-server"
  }]
}

upstreams = [
  { ip = "localhost", port = 2000 }
]