Server configuration

With our Service Storefront as a Service offering, you can also customize the NGINX configuration for your specific needs. Just have a look at Github at the default configuration.

This file contains a template, that also supports the usage of environment variables. By default the following values are available:

Name	Value (Example)
MAKAIRA_API_INSTANCE	stage
MAKAIRA_API_URL	https://shop.makaira.io
MAKAIRA_ASSET_URL	https://storefront-preview.s3.eu-central-1.amazonaws.com
NODE_ENV	production
PRODUCTS_PER_PAGE	50
RUNS_ON_HEROKU	true
SHOP_DOMAIN	https://shop.makaira.cloud
SHOP_ID	1

In order to use an environment variable inside the template, you'll need to use the following syntax:

listen <%= ENV["PORT"] %>;

Additionally, you can also use all common features of NGINX. You can find the documentation of NGINX directly on their website: NGINX Documentation.

Basic Auth

By default, your storefront is protected with a basic auth login. If you want multiple accounts for your storefront, please contact our support team.

Please use the command below to generate a new basic auth user. Afterwards, you can send to our support team your newly generated basic auth user.

htpasswd -B config/.htpasswd USER_NAME

📘
If you have htpasswd not installed, please follow one of these guides: Install htpasswd on Ubuntu/Debian, Use htpasswd on Windows or Use htpasswd on macOS

Configuration Examples

Pre Go Live Routing

The following configuration is useful if you want to forward the whole traffic to your shop system. You can do that before you go live with your new storefront and have already switched your DNS record to the new storefront.

http {
  ...

  location / {
    # Redirect all traffic to HTTPS
    if ($http_x_forwarded_proto != "https") {
      return 301 https://$host$request_uri;
    }

    proxy_pass            http://example.com; # Please put the url of your shop system here
    proxy_read_timeout    120s;
    proxy_connect_timeout 15s;
    proxy_send_timeout    90s;
    proxy_set_header      Host "example.com"; # Please put the address of this storefront here
    proxy_set_header      X-Real-IP $http_x_real_ip;
    proxy_set_header      X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header      X-Forwarded-Proto $http_x_forwarded_proto;
    proxy_set_header      HTTPS $http_https;
  }
}

IP Whitelisting

Besides basic auth, it is also possible to define IP addresses that can access the storefront without additional authentication.

server {
  ...

  location / {
    ...

    # Allow specified IP addresses additionally to basic auth
    satisfy any;
    allow 127.0.0.1;
    deny all;

    ...
  }
}

Failover

Use this configuration, if you want to forward requests to shop system, that cannot be served by storefront and are throwing an error.

http {
  ...
  # Enable this part if you want to use error page failover
  proxy_busy_buffers_size   512k;
  proxy_buffers             4 512k;
  proxy_buffer_size         256k;
  proxy_intercept_errors    on;
  recursive_error_pages     on;

  location / {
    # Redirect all traffic to HTTPS
    if ($http_x_forwarded_proto != "https") {
      return 301 https://$host$request_uri;
    }

    # Enable error_page if you want to use error page failover
    error_page 404 500 501 502 503 504 505 506 507 508 510 511 = @failover_target;

    proxy_set_header      Host $http_host;
    proxy_set_header      X-Real-IP $http_x_real_ip;
    proxy_set_header      X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header      X-Forwarded-Proto $http_x_forwarded_proto;
    proxy_set_header      HTTPS $http_https;
    proxy_set_header      Accept-Encoding "gzip,deflate";
    proxy_set_header      Connection "";
    proxy_set_header      Proxy "";
    proxy_set_header      X-Country-Code $http_x_country_code;

    proxy_redirect          off;
    proxy_pass              http://app_server;
  }

  # Failover target
  location @failover_target {
    proxy_pass            http://example.com; # Please put the url of your shop system here
    proxy_read_timeout    120s;
    proxy_connect_timeout 15s;
    proxy_send_timeout    90s;
    proxy_set_header      Host "example.com"; # Please put the address of this storefront here
    proxy_set_header      X-Real-IP $http_x_real_ip;
    proxy_set_header      X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header      X-Forwarded-Proto $http_x_forwarded_proto;
    proxy_set_header      HTTPS $http_https;
  }
}

Failover Multiple Times

It's also possible to failover more than once. For example, your storefront fails over to your shop, but it also returns a non 200 response. After that, you can again fail over to another failover target. This could also be the storefront again. To fail over in a failover target, just define the error_page [HTTP_ERROR] = @NEXT_FAILOVER_TARGET in your first failover section. Example:

http {
  ...
  # Enable this part if you want to use error page failover
  proxy_busy_buffers_size   512k;
  proxy_buffers             4 512k;
  proxy_buffer_size         256k;
  proxy_intercept_errors    on;
  recursive_error_pages     on;

  location / {
    # Redirect all traffic to HTTPS
    if ($http_x_forwarded_proto != "https") {
      return 301 https://$host$request_uri;
    }

    # Enable error_page if you want to use error page failover
    error_page 404 500 501 502 503 504 505 506 507 508 510 511 = @failover_target;

    proxy_set_header      Host $http_host;
    proxy_set_header      X-Real-IP $http_x_real_ip;
    proxy_set_header      X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header      X-Forwarded-Proto $http_x_forwarded_proto;
    proxy_set_header      HTTPS $http_https;
    proxy_set_header      Accept-Encoding "gzip,deflate";
    proxy_set_header      Connection "";
    proxy_set_header      Proxy "";
    proxy_set_header      X-Country-Code $http_x_country_code;

    proxy_redirect          off;
    proxy_pass              http://app_server;
  }

  # Failover target
  location @failover_target {
    # Fail over to the second target if 404 is returned
    error_page 404 = @second_failover_target;
  
    proxy_pass            http://example.com; # Please put the url of your shop system here
    proxy_read_timeout    120s;
    proxy_connect_timeout 15s;
    proxy_send_timeout    90s;
    proxy_set_header      Host "example.com"; # Please put the address of this storefront here
    proxy_set_header      X-Real-IP $http_x_real_ip;
    proxy_set_header      X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header      X-Forwarded-Proto $http_x_forwarded_proto;
    proxy_set_header      HTTPS $http_https;
  }

  # Second failover target
  location @second_failover_target {
    proxy_pass            http://example.com; # Please put the url of the second failover target here
    proxy_read_timeout    120s;
    proxy_connect_timeout 15s;
    proxy_send_timeout    90s;
    proxy_set_header      Host "example.com"; # Please put the address of this storefront here
    proxy_set_header      X-Real-IP $http_x_real_ip;
    proxy_set_header      X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header      X-Forwarded-Proto $http_x_forwarded_proto;
    proxy_set_header      HTTPS $http_https;
  }
}

Forward specific routes to your shop system

If you want to forward the whole traffic for specific routes to your shop system directly, you can use the following configuration. For the configuration of the route, you can use regular expressions. For more information about configuring locations in NGINX, please go and visit this blog post by DigitalOcean: Understanding Nginx Server and Location Block Selection Algorithms

http {
  ...
  location / {
    ...
  }

  # Custom location with direct failover
  location ~* ^(/api/) {
    try_files /dev/null @failover_target;
  }

  # Failover target
  location @failover_target {
    proxy_pass            http://example.com; # Please put the url of your shop system here
    proxy_read_timeout    120s;
    proxy_connect_timeout 15s;
    proxy_send_timeout    90s;
    proxy_set_header      Host "example.com"; # Please put the address of this storefront here
    proxy_set_header      X-Real-IP $http_x_real_ip;
    proxy_set_header      X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header      X-Forwarded-Proto $http_x_forwarded_proto;
    proxy_set_header      HTTPS $http_https;
  }
}

Trailing Slash Enforcement
If your URL should always end with a slash (/), then you can use this option. It will append a slash (/) to URLs without one.

http {
  ...
  location / {
    ...
  }

  # Always append slash
  port_in_redirect off;
  location ~ ^([^.\?]*[^/])$ {
    return 301 $uri/;
  }
}

A/B Testing Makaira storefront vs. the old shop frontend

If you want to see how good the Makaira storefront performs in comparison to your current shop frontend, you can use our A/B Testing feature.

Firstly, you need to create a new experiment in your Makaira admin console. (e.g. https://your-subdomain.makaira.io)

There you can choose A/B Experiments and then Create. We recommend to use MakairaStorefront as the title for your A/B Test.

After that, you can edit the nginx configuration of your storefront. For that please use the following code snippet:

Important: Failover needs to be enabled to use this feature! Otherwise, your storefront will stop working!

http {
  # Enable this part if you want to use A/B Testing between the Makaira storefront and your old one
  map "" $experiment {
    default 000; # Put in here the experiment id from the Makaira admin console
  }

  split_clients "${http_x_forwarded_for}AAA" $variant {
    50%     MakairaStorefront; # Replace this with the Title of your experiment
    50%     original; # Leave this value as is
  }

  map $cookie_mak_experiments $mak_experiments {
    default "";
    "" "mak_experiments=%5B%7B%22experiment%22%3A$experiment%2C%22variation%22%3A%22$variant%22%7D%5D;Path=/;Max-Age=100000";
  }
  
  server {
    ...
    location / {
      # Enable error_page if you want to use error page failover
      # Just an example for more details take a look at the full failover example on this documentation page
      error_page 404 500 501 502 503 504 505 506 507 508 510 511 = @failover_target;
      # END failover

      # Required for A/B Testing
      # IMPORTANT: needs to be defined AFTER error_page from failover
      add_header Set-Cookie $mak_experiments;

      if ($http_cookie ~* "mak_experiments=.*original.*") {
        return 404; # Trigger failover
      }
      if ($variant = "original") {
        return 404; # Trigger failover for clients without a cookie (yet)
      }
      # END A/B Testing
      ...
    }

    # Failover target
    location @failover_target {
      # Required for A/B Testing
      add_header Set-Cookie $mak_experiments;
      # END A/B Testing

      # The rest of the failover target configuration can be found above on this documentation page
            ...
    }
  }
}