When deploying GAIA UI a common approach is to build a Linux container image. It's normally done using Docker. You can then deploy that container image in one of a few possible ways.

Using Linux containers has several advantages including security, replicability, simplicity, and others.

In a hurry and already know this stuff? Jump to the Dockerfile below.


Build a Docker Image for GAIA UI

This section will show you how to build a Docker image for GAIA UI from scratch, based on the official Python image.

This is what you would want to do in most cases, for example:

  • Using Kubernetes or similar tools
  • When running on a Raspberry Pi
  • Using a cloud service that would run a container image for you, etc.

Dockerfile

This Dockerfile is used to create a Docker image that builds the GAIA UI using Node.js and serves it using Nginx. It has two stages: one for building the UI and the other for preparing it for production. The UI source code is copied, dependencies are installed, and a build script is executed in the first stage. In the second stage, the built UI, configuration files, and version information are copied to an Nginx image. This Docker image is designed to be ready for production deployment and can be customized by changing the base image and updating dependencies as needed.

Dockerfile 
# syntax=docker/dockerfile:1

### Stage 1 Build Application ###
FROM node:20-slim as build

# Argument to control if Vite includes sourcemaps in the build. Useful for debugging.
# 'false' by default to avoid exposing code details in production.
ARG VITE_SOURCEMAP='false'

# Setting up the environment for pnpm, a fast, disk space-efficient package manager
ENV PNPM_HOME="/pnpm"
ENV PATH="$PNPM_HOME:$PATH"
ARG THEME_MODE=dark

# Enable corepack to manage Node.js package managers
RUN corepack enable

# Copy the application's source code into the container
COPY . /gaia_ui_build
WORKDIR /gaia_ui_build

# Update npm to the latest version
RUN npm install -g npm

# Install pnpm globally, using force to ensure installation
RUN npm install -g pnpm --force

# Install dependencies using pnpm, with a cache mount for efficiency
RUN --mount=type=cache,id=pnpm,target=/pnpm/store pnpm install
RUN pnpm run build


### Stage 2 Ready Production ###
FROM nginx:alpine as GaiaUI

# Set and expose the port for GAIA UI, defaults to 8080
ARG PORT=8080
ENV PORT=$PORT

# Set GAIA API URL to be used by the GAIA UI
ARG API_URL=http://localhost:8085
ENV API_URL=$API_URL

# Install bash in the nginx container, useful for scripting
RUN apk add --no-cache bash perl

# Operate as the root user
USER root:root

# Set the working directory
WORKDIR /gaia_ui

# Copy pre-script from build stage for environment variable replacement
COPY --from=build /gaia_ui_build/gaia_ui_prescript.sh /docker-entrypoint.d/gaia_ui_prescript.sh

# Copy the NGINX configuration template from the build stage
COPY --from=build /gaia_ui_build/ngnix.conf ./template/ngnix.conf.tpl

# Copy the built application from the build stage to NGINX's html directory
COPY --from=build /gaia_ui_build/dist /usr/share/nginx/html

# Copy config files from the build stage as templates
COPY --from=build /gaia_ui_build/dist/assets/config.js ./template/config.js.tpl
COPY --from=build /gaia_ui_build/dist/assets/config.development.js ./template/config.development.js.tpl

# Include version file for reference
COPY --from=build /gaia_ui_build/.gaia-ui-version .gaia-ui-version

# Ensure the pre-script is executable
RUN chmod +x /docker-entrypoint.d/gaia_ui_prescript.sh

# Expose the specified port
EXPOSE $PORT

# Start NGINX with the specified command
CMD ["nginx", "-g", "daemon off;"]

Detailed Breakdown

Stage 1: Build Application

This stage is responsible for building the web application.

  1. FROM node:20-slim as build: This sets the base image to Node.js 20-slim and names this stage as "build". It's used for building the application.

  2. ARG VITE_SOURCEMAP='false': Defines an argument VITE_SOURCEMAP with a default value of 'false'.

  3. ENV PNPM_HOME="/pnpm" and ENV PATH="$PNPM_HOME:$PATH": Set environment variables for the PNPM package manager.

  4. RUN corepack enable: Enables the Corepack package manager.

  5. COPY . /gaia_ui_build: Copies the contents of the current directory into a directory called /gaia_ui_build inside the image.

  6. WORKDIR /gaia_ui_build: Sets the working directory to /gaia_ui_build.

  7. RUN npm install -g npm: Updates npm to the latest version.

  8. RUN npm install -g pnpm --force: Installs the PNPM package manager.

  9. RUN --mount=type=cache,id=pnpm,target=/pnpm/store pnpm install: Uses a cache to install project dependencies using PNPM.

  10. RUN pnpm run build: Runs a build script to build the web application.

Stage 2: Ready for Production

This stage prepares the application for production deployment using Nginx.

  1. FROM nginx:alpine as GaiaUI: Sets the base image to Nginx Alpine Linux and names this stage as "GaiaUI".

  2. ARG PORT=8080: Declares a build argument PORT with a default value of 8080. This sets the port for the Nginx server.
  3. ENV PORT=$PORT: Sets an environment variable PORT equal to the build argument PORT. This is used to configure Nginx to listen on the specified port.
  4. ARG API_URL=http://localhost:8085: Introduces another build argument API_URL with a default of http://localhost:8085.
    1. Used to specify the API endpoint that the UI will interact with.
  5. ENV API_URL=$API_URL: Sets an environment variable API_URL equal to the build argument API_URL.

  6. RUN apk add --no-cache bash perl: Installs Bash and PERL in the Nginx image.

  7. USER root:root: Sets the user to root.

  8. WORKDIR /gaia_ui: Sets the working directory to /gaia_ui.

  9. COPY --from=build /gaia_ui_build/gaia_ui_prescript.sh /docker-entrypoint.d/gaia_ui_prescript.sh: Copies a prescript from the build stage to the /docker-entrypoint.d/ directory. This script may replace environment variables in files.

  10. COPY --from=build /gaia_ui_build/ngnix.conf ./template/ngnix.conf.tpl: Copies an NGINX configuration template file.

  11. COPY --from=build /gaia_ui_build/dist /usr/share/nginx/html: Copies the built application from the build stage to the NGINX HTML folder.

  12. Copies template config files:

    • COPY --from=build /gaia_ui_build/dist/assets/config.js ./template/config.js.tpl
    • COPY --from=build /gaia_ui_build/dist/assets/config.development.js ./template/config.development.js.tpl

  13. COPY --from=build /gaia_ui_build/.gaia-ui-version .gaia-ui-version: Copies the application version for reference.

  14. RUN chmod +x /docker-entrypoint.d/gaia_ui_prescript.sh: Makes the prescript executable.

  15. EXPOSE 80: Exposes port 80 for incoming HTTP traffic.

  16. CMD ["nginx", "-g", "daemon off;"]: Sets the command to start Nginx when the container is run.

Building the Dockerfile

Building a Docker image from this Dockerfile involves using the docker build command. You can customize the build process by specifying various arguments, allowing for different configurations of the resulting image.

Basic Build Instructions

  1. Bare Minimum Build: To build the Docker image with the default settings (as specified in the Dockerfile), navigate to the directory containing the Dockerfile and run:

    docker build -t my-gaia-ui .
    • -t my-gaia-ui assigns the tag my-gaia-ui to the built image.
    • . specifies the current directory as the build context.

Building with Custom Arguments

  1. Available Arguments: The Dockerfile includes several build-time arguments (ARG) that allow for customizing the build. Here is a list of the available arguments and their default values:

    • VITE_SOURCEMAP:  If set to true, Vite will add sourcemaps to the build, aiding in debugging but revealing the code structure. Default is true.
    • THEME_MODE: Defines the theme mode for the UI. Default is dark. Options [dark, light ]

  2. Example Builds with Custom Arguments:

    1. To build with sourcemaps:

      docker build --build-arg VITE_SOURCEMAP='true' -t your-image-name .


    2. to build with a light theme as default:

      docker build --build-arg THEME_MODE=light -t your-image-name .


  • Each --build-arg flag allows you to override the default argument value specified in the Dockerfile.

Important

If you have a Docker Desktop or Docker Engine version below 23.0, you need to enable the "Docker Buildkit" in order to build these images, otherwise, the build process will fail.

Here you can see how to enable or configure it by default.



Running a Container from the Built Image

After building the Docker image from the Dockerfile, you can run a container using the docker run command. This section provides instructions on how to do so, including how to utilize various environment variables for customizing the runtime behavior of your container.

Start the Docker Container

  • Run a container based on your image:
$ docker run -d --name gaia-ui-container -p 8080:8800 myimage

Basic Run Instructions

  1. Bare Minimum Run: To run a container with the default settings, use the following command:

     docker run -d -p 8080:8080 --name gaia-ui-container
    • -d runs the container in detached mode (in the background).
    • -p 8080:80 maps port 8080 of the container to port 8080 on the host. Adjust the port numbers as needed based on the PORT environment variable.
    • --name gaia-ui-container is the tag name of the image you built.

Running with Custom Environment Variables

  1. Available Environment Variables: The Dockerfile defines several environment variables (ENV) that you can override at runtime. Here is a list of the available environment variables:

    • THEME_MODE,PORT,API_URL: Various settings for the GAIA UI.
  2. Example Runs with Custom Environment Variables:

    • To run with a custom port:

      docker run -d -p 8080:9090 -e PORT=9090 --name gaia-ui-container

    • To run with a custom API URL:

      docker run -d -p 8080:8080 -e API_URL='http://api.example.com' --name gaia-ui-container

    • To run with specific theme:

      docker run -d -p 8080:8080 -e THEME_MODE='light' --name gaia-ui-container
  • The -e flag is used to set environment variables in the container. These variables can override the defaults set in the Dockerfile.
  • Ensure the port mappings (-p) align with the PORT environment variable.
  • Replace example values with actual values relevant to your setup.

Environment Variables Table

Below is a table listing all the environment variables used in the Dockerfile, along with their default values and descriptions.

NameDefaultDescription
VITE_SOURCEMAP'false'

Determines if Vite will add sourcemaps to the build, aiding in debugging. 'true' enables sourcemaps, revealing the code structure.

Applicable only on the build stage

THEME_MODE'dark'Defines the theme mode for the UI.
PNPM_HOME"/pnpm"

Specifies the home directory for PNPM.

Applicable only on the build stage

PORT8080Sets the port for serving the application, used in the Nginx configuration.
API_URLhttp://localhost:8085Sets the URL of the GAIA API to be called from the GAIA UI.

Changing the Base Image

To change the base image to another Node base image, follow these steps:

  1. Locate the FROM Directive: In your Dockerfile, look for the FROM directive. This directive specifies the base image and its version.

    FROM node:20-slim as build

    In this example, the base image is node:20-slim.

  2. Choose a New Node.js Version:

    • Decide on the Node.js version you want to use. You can find the available official Node.js images on Docker Hub. Choose a version that is compatible with your application's requirements.

  3. Modify the FROM Directive:

    • Replace the existing Node.js version in the FROM directive with the version you want to use. For example, if you want to use Node.js version 14, update it as follows:

      FROM node:21-alpine3.18 as build

      If you need a more specific version, you can use the full version tag, such as node:21-alpine3.18

  4. Rebuild the Docker Image:

    • Build the Docker image again with the updated Dockerfile. This will use the new base image for the ui.

      docker build -t my-gaia-ui .

      Replace my-gaia-ui with a suitable name for your Docker image.

Same process can be done to replace the nginx image

  • No labels