Managing Runtime env variables in JS Vite applications with Docker and Nginx

Table of contents

Introduction

In modern web development, managing environment configurations across different stages of deployment can be a challenging task. This post dives into an effective solution using Javascript & Vite, Docker and Nginx. By the end of this post, you will understand how to manage runtime environment variables effectively, ensuring smoother transitions from development to production.

The challenge

Traditionally, handling different configurations for different environments requires creating separate Docker images for each scenario, which is inefficient and error-prone. This approach increases the risk of discrepancies between environments, leading to the dreaded “it works on my machine” syndrome.

The solution

Our strategy focuses on using a single Docker image across all environments, injecting runtime variables dynamically. This ensures consistency and reliability in deployments, and here’s how we do it:

Code Breakdown

1. Dockerfile Configuration:

The Dockerfile is set up to use Nginx and to copy our built Vite application into the Nginx server:

FROM nginx:alpine

COPY dist /usr/share/nginx/html

COPY default.conf /etc/nginx/conf.d/default.conf
COPY entrypoint.sh /entrypoint.sh
RUN chmod +x /entrypoint.sh
EXPOSE 80
ENTRYPOINT ["/entrypoint.sh"]
CMD ["nginx", "-g", "daemon off;"]

2. Nginx Configuration (default.conf):

This configuration ensures that all requests are redirected to index.html, facilitating SPA routing:

server {
    listen 80;

    location / {
        root   /usr/share/nginx/html;
        index  index.html index.htm;
        try_files $uri /index.html;
    }
}

3. Entrypoint Script (entrypoint.sh):

It replaces placeholders in index.html with actual environment variables:

#!/bin/sh

# Replace placeholders with environment variable values in index.html
sed -i "s|__BACKEND_URL__|${BACKEND_URL}|g" /usr/share/nginx/html/index.html
sed -i "s|__SERVICE_VERSION__|${SERVICE_VERSION}|g" /usr/share/nginx/html/index.html

# Start the main process (e.g., Nginx)
exec "$@"

4. Frontend Setup (index.html):

Here, we initialize global variables which will be replaced by entrypoint.sh. It provides default values which will be used when you are running your application locally. The variables will be available throughout your web application on globalThis.appConfig.

<script>
  globalThis.appConfig = {
    BACKEND_URL: "http://your-default-backend-url",
    SERVICE_VERSION: "local",
  };

  if (
    window.location.hostname !== "localhost" &&
    window.location.hostname !== "127.0.0.1"
  ) {
    globalThis.appConfig.BACKEND_URL = "__BACKEND_URL__";
    globalThis.appConfig.SERVICE_VERSION = "__SERVICE_VERSION__";
  }
</script>

Security Considerations

Be cautious with environment variables. Avoid embedding sensitive data directly into your frontend code. Use backend services to handle sensitive operations.

Conclusion

This setup streamlines the process of managing runtime environment variables in a frontend application, making your deployments consistent and reliable. By understanding and implementing this method, you can enhance the efficiency and stability of your web application deployments.