Add URL configuration to Docker images by nrichers · Pull Request #674 · validmind/documentation

nrichers · Mar 17, 2025

Internal Notes for Reviewers

This PR lets you configure the Docker image for our static docs site via Kubernetes manifest or a config file.

Two parameters can be configured, documented in URL configuration for Docker:

VALIDMIND_URL — where to access our platform
JUPYTERHUB_URL — where to access JupyterHub

Configure via Kube manifest: <<< SPENCER, VERIFY THIS WORKS BEYOND MY BASIC TESTING? 🐹

   apiVersion: apps/v1
   kind: Deployment
   metadata:
     name: validmind-docs
   spec:
     template:
       spec:
         containers:
         - name: validmind-docs
           env:
           - name: VALIDMIND_URL
             value: "https://your-custom-app.validmind.ai"
           - name: JUPYTERHUB_URL
             value: "https://your-custom-jupyter.validmind.ai"

Configure via config.json, generated with the Docker image:

  {
     "VALIDMIND_URL": "https://your-custom-app.validmind.ai",
     "JUPYTERHUB_URL": "https://your-custom-jupyter.validmind.ai"
   }

How it works

A new _quarto-docker.yml profile includes pre-render and post-render steps to generate a documentation site with configurable URL placeholders. When Docker starts the container image built from this docs site, the placeholder URLs are then replaced with the URLs you specify (or safe fallback URLs), making the site configurable.

Pre-render

We replace the relevant URLs in _variables.yml with unique placeholders that contain configurable-url and generate a config.json with the default URLs:

Found URLs in _variables.yml:
VALIDMIND_URL: https://app.prod.validmind.ai
JUPYTERHUB_URL: https://jupyterhub.validmind.ai
Successfully generated config.json from _variables.yml
Modified _variables.yml with placeholder values:
VALIDMIND_URL: https://app.prod.validmind-configurable-url.ai
JUPYTERHUB_URL: https://jupyterhub.validmind-configurable-url.ai

Post-render

We restore _variables.yml.

Docker startup

When you start Docker after building the image, an entrypoint script configures the site using:

URL values specified via direct environment variables, e.g. a K8s manifest
URL values specified in config.json
As a fallback, hardcoded public URL defaults

Starting the Docker container on http://localhost:4444/ ...
...
==== Start ValidMind URL configuration ====
Initializing ValidMind documentation site...
Looking for values in config file: /usr/share/nginx/html/config.json
Using VALIDMIND_URL from config: https://app.prod.validmind.ai
Using JUPYTERHUB_URL from config: https://jupyterhub.validmind.ai
Found placeholders:
14 instances of https://app.prod.validmind-configurable-url.ai
59 instances of https://jupyterhub.validmind-configurable-url.ai
Replacing URL placeholders in HTML files...
Replacing URL placeholders in search.json...
After replacement:
0 instances of https://app.prod.validmind-configurable-url.ai
0 instances of https://jupyterhub.validmind-configurable-url.ai
✓ URL replacement completed successfully
==== URL configuration complete ====
...

How to test

gh pr checkout 674
cd site
make docker-build

Output in site/_site should now show placeholder URLs that contain configurable-url. For example:

site/_site/developer/get-started-validmind-library.html:
  2267  </div>
  2268: <p>After you <a href="https://app.prod.validmind-configurable-url.ai"><strong>sign up</strong></a> for ValidMind to get access, try one of our getting started guides:</p>
  2269  <div id="listing-developer-getting-started" class="quarto-listing quarto-listing-container-grid">

site/_site/developer/samples-jupyter-notebooks.html:
  2070  <div class="w-30-ns mt2 pb3">
  2071: <p><a href="https://jupyterhub.validmind-configurable-url.ai/" class="button button-green" target="_blank"><i class="fa-solid fa-code" aria-label="code"></i> Try Notebooks on JupyterHub</a></p>
  2072  </div>

Next, start the Docker image:

make docker-serve

Opening up the site on http://localhost:4444/ in your browser should show the actual, correct URLs specified in config.json.

Inspect http://localhost:4444/developer/get-started-validmind-library.html:

<a href="https://app.prod.validmind.ai/" data-original-href="https://app.prod.validmind.ai/" target="_blank" rel="noopener" class="external"><strong>sign up</strong></a>

Inspect http://localhost:4444/developer/samples-jupyter-notebooks.html:

<p><a href="https://jupyterhub.validmind.ai/" class="button button-green external" target="_blank" data-original-href="https://jupyterhub.validmind.ai/" rel="noopener"><i class="fa-solid fa-code" aria-label="code"></i> Try Notebooks on JupyterHub</a></p>

External Release Notes

You can now configure the Docker image for our static docs site via Kubernetes manifest or a config file. Two parameters can be configured:

VALIDMIND_URL — Where to access the ValidMind Platform
JUPYTERHUB_URL — Where to access JupyterHub

This feature lets you configure the site’s Docker image to match your specific requirements, simplifying deployment in your own infrastructure.

You can set these URLs using one of the following supported methods: URL configuration for Docker

github-actions · Mar 19, 2025

PR Summary

This pull request introduces several enhancements to the Docker configuration for the ValidMind documentation site. The key changes include:

Dockerfile Enhancements:
- Added installation of jq for JSON handling.
- Introduced a new entrypoint script docker_entrypoint.sh to replace URL placeholders with actual values at runtime.
- Made the entrypoint script executable.
Dynamic URL Configuration:
- Introduced a config.json file to store default URL values for VALIDMIND_URL and JUPYTERHUB_URL.
- Updated various documentation files to use placeholders for URLs, which are replaced at runtime by the entrypoint script.
Makefile and Build Process:
- Added new Makefile targets docker-site and docker-site-lite for building the site with Docker-specific configurations.
- Updated the docker-build target to use the new docker-site-lite process.
Kubernetes Configuration:
- Added a sample Kubernetes manifest validmind-docs.yaml for deploying the documentation site with configurable URLs via environment variables or a ConfigMap.
Scripts for URL Handling:
- Added modify_urls.sh to replace actual URLs with placeholders during the build process.
- The docker_entrypoint.sh script handles the replacement of placeholders with actual URLs at runtime, using environment variables or config.json as sources.

These changes allow for more flexible deployment of the documentation site, enabling dynamic configuration of URLs based on the deployment environment.

Test Suggestions

Test the Docker image build process to ensure it completes without errors.
Run the Docker container and verify that the URL placeholders are correctly replaced with actual values.
Test the site functionality by accessing it through the configured URLs in a browser.
Verify that the Kubernetes deployment using the provided manifest works as expected.
Check that the config.json file is correctly generated and used by the entrypoint script.
Ensure that the modify_urls.sh script correctly replaces URLs with placeholders during the build process.

site/releases/2024/2024-oct-22/release-notes.qmd

validmind-docs.yaml

github-actions · Mar 20, 2025

PR Summary

This pull request introduces several enhancements to the Docker configuration for the ValidMind documentation site. The key changes include:

Dockerfile Enhancements:
- Added installation of jq for JSON handling.
- Introduced a new entrypoint script docker_entrypoint.sh to replace URL placeholders with actual values.
- Made the entrypoint script executable.
Dynamic URL Configuration:
- Introduced a config.json file to store fallback URL values for VALIDMIND_URL and JUPYTERHUB_URL.
- Added a script modify_urls.sh to replace actual URLs with placeholders during the Docker image build process.
- Updated various documentation files to use URL placeholders, allowing dynamic URL configuration at runtime.
Makefile and Build Process:
- Added new Makefile targets docker-site and docker-site-lite for rendering the site with Docker profiles.
- Updated docker-build to use the new docker-site-lite target.
Kubernetes Configuration:
- Added a sample Kubernetes manifest validmind-docs.yaml for deploying the documentation site with configurable URLs using environment variables or a ConfigMap.
Documentation Updates:
- Updated README and other markdown files to reflect the new URL configuration process.

These changes aim to improve the flexibility and maintainability of the documentation site deployment, particularly in containerized environments.

Test Suggestions

Test the Docker image build process to ensure jq is installed and the entrypoint script is executable.
Verify that the docker_entrypoint.sh script correctly replaces URL placeholders with environment variable values.
Test the fallback mechanism using config.json when environment variables are not set.
Ensure that the site renders correctly with the new Docker profile by running make docker-site and make docker-site-lite.
Deploy the site using the provided Kubernetes manifest and verify that the URLs are correctly configured.
Check that all links in the documentation resolve correctly when accessed through the Docker container.

nibalizer

One note and one question.

Q: What are the startup time implications? Just a couple seconds or more? Does failing to template hard crash the server or just some links are broken?

site/scripts/docker_entrypoint.sh

validmind-docs.yaml

nrichers · Mar 20, 2025

Q: What are the startup time implications? Just a couple seconds or more?

@nibalizer just checked and the script adds <10 seconds to the startup on my Mac with whatever default resources Docker Desktop assigns.

Does failing to template hard crash the server or just some links are broken?

We should fall back to the public defaults but if even this fails, you just get some URLs that 404. I verified this during script development.

…ronment-variables

validbeck

This looks good to me, but the last time I checked any self-hosted stuff was not to be exposed to users/in general docs release notes, and the way this PR is tagged will have the notes show up in our collation.

…ronment-variables

github-actions · Mar 21, 2025

A PR preview is available: Preview URL

nrichers · Mar 22, 2025

This looks good to me, but the last time I checked any self-hosted stuff was not to be exposed to users/in general docs release notes, and the way this PR is tagged will have the notes show up in our collation.

This is a good point — but the Docker image also has uses beyond self-hosting. I rewrote the release notes to mention testing during development, similar to how you can run the frontend on localhost, or accessing the full docs site locally.

nrichers marked this pull request as draft March 17, 2025 21:46

nrichers added the internal Not to be externalized in the release notes label Mar 17, 2025

nrichers force-pushed the nrichers/sc-8752/investigate-passing-in-environment-variables branch from 02a303f to 458bca1 Compare March 17, 2025 22:43

nrichers added the infrastructure Docs infra changes label Mar 19, 2025

nrichers changed the title ~~Nrichers/sc 8752/investigate passing in environment variables~~ Add URL configuration to Docker images Mar 19, 2025

Enable initial URL configuration for docs site in Docker images

9d7a08e

nrichers force-pushed the nrichers/sc-8752/investigate-passing-in-environment-variables branch from 7c43a2a to 9d7a08e Compare March 19, 2025 21:47

nrichers requested review from nibalizer and validbeck March 19, 2025 21:51

nrichers removed the internal Not to be externalized in the release notes label Mar 19, 2025

nrichers commented Mar 19, 2025

View reviewed changes

site/releases/2024/2024-oct-22/release-notes.qmd Show resolved Hide resolved

nrichers commented Mar 19, 2025

View reviewed changes

validmind-docs.yaml Show resolved Hide resolved

nrichers marked this pull request as ready for review March 20, 2025 03:33

nibalizer approved these changes Mar 20, 2025

View reviewed changes

site/scripts/docker_entrypoint.sh Show resolved Hide resolved

validmind-docs.yaml Show resolved Hide resolved

Merge branch 'main' into nrichers/sc-8752/investigate-passing-in-envi…

bbef555

…ronment-variables

validbeck approved these changes Mar 20, 2025

View reviewed changes

nrichers added 2 commits March 21, 2025 12:40

Remove variables from YAML front matter in two files

8cbf8ed

Merge branch 'main' into nrichers/sc-8752/investigate-passing-in-envi…

cd2b164

…ronment-variables

nrichers merged commit 8c0233e into main Mar 22, 2025
2 of 3 checks passed

nrichers deleted the nrichers/sc-8752/investigate-passing-in-environment-variables branch March 22, 2025 18:06

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Add URL configuration to Docker images#674

Add URL configuration to Docker images#674
nrichers merged 4 commits intomainvalidmind/documentation:mainfrom
nrichers/sc-8752/investigate-passing-in-environment-variablesvalidmind/documentation:nrichers/sc-8752/investigate-passing-in-environment-variablesCopy head branch name to clipboard

nrichers commented Mar 17, 2025 •

edited

Loading

Uh oh!

github-actions bot commented Mar 19, 2025

Uh oh!

Uh oh!

Uh oh!

github-actions bot commented Mar 20, 2025

Uh oh!

nibalizer left a comment

Uh oh!

Uh oh!

Uh oh!

nrichers commented Mar 20, 2025 •

edited

Loading

Uh oh!

validbeck left a comment

Uh oh!

github-actions bot commented Mar 21, 2025

Uh oh!

nrichers commented Mar 22, 2025

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Search code, repositories, users, issues, pull requests...

Conversation

nrichers commented Mar 17, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Internal Notes for Reviewers

How it works

Pre-render

Post-render

Docker startup

How to test

External Release Notes

Uh oh!

github-actions bot commented Mar 19, 2025

PR Summary

Test Suggestions

Uh oh!

Uh oh!

Uh oh!

github-actions bot commented Mar 20, 2025

PR Summary

Test Suggestions

Uh oh!

nibalizer left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

nrichers commented Mar 20, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

validbeck left a comment

Choose a reason for hiding this comment

Uh oh!

github-actions bot commented Mar 21, 2025

Uh oh!

nrichers commented Mar 22, 2025

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

nrichers commented Mar 17, 2025 •

edited

Loading

nrichers commented Mar 20, 2025 •

edited

Loading