Getting started with Squidex - the big picture
#squidex#docker#nginx#webdev
Theodor Heiselberg

Theodor Heiselberg @sukkergris

About: Developer since 2008

Location:
Denmark
Joined:
Jan 11, 2024

Getting started with Squidex - the big picture

Publish Date: Aug 1
0 0

The Big Picture: The Philosophy Behind Our Setup

Disclaimer: Only tested on Mac Silicon
If you're ready to integrate a headless CMS into your project, you're in the right place. We're going to build a solid foundation for local development, and we'll do it by keeping our environment as close to production as possible.

My projects consistently use NGINX—even for local development. For my reasoning, you can read more here:

Nginx for Local Development: Really?

The Red Pill of Software Delivery: Unmasking Magic Code and Building for Reality

The gist of it is this: I'll be showcasing how to set up a development environment for a Single Page Application (SPA) and a backend running in a devcontainer, using Squidex as our headless CMS.

To keep this environment close to a real-world scenario, we'll be using local domain names. This means we'll have one domain for our main frontend (the SPA) and another for the Squidex administration app, which is also a SPA.

This approach gives us a reliable, consistent, and realistic development setup that will make our transition to production much smoother.

The Development Environment

As you can see overview we will be routing all of our development server endpoints though Nginx.

Let's start building our devcontainer environment!

The devcontainer

Since this post is all about how to get started using Squidex I won't be covering much about how to setup a devcontainer.

.devcontainer/devcontainer.json

{
  "name": "Dotnet 9 and Elm Dev Container (Alpine + Compose)",
  "dockerComposeFile": "docker-compose.yml",
  "service": "dev",
  "workspaceFolder": "/workspace",
  "mounts": [
    "source=my-app-elm-devcontainer,target=/home/container-user/.elm,type=volume"
  ],
  "customizations": {
    "vscode": {
      "settings": {
        "terminal.integrated.defaultProfile.linux": "zsh"
      },
      "extensions": [
        "ms-vscode-remote.remote-containers",
        "Elmtooling.elm-ls-vscode",
        "ms-dotnettools.csharp",
        "william-voyek.vscode-nginx",
        "vscodevim.vim",
        "ms-dotnettools.csdevkit",
        "EditorConfig.EditorConfig",
        "humao.rest-client",
        "esbenp.prettier-vscode",
        "DotJoshJohnson.xml",
        "streetsidesoftware.code-spell-checker",
        "streetsidesoftware.code-spell-checker-danish",
        "bradlc.vscode-tailwindcss",
        "kamikillerto.vscode-colorize",
        "Ionide.Ionide-fsharp",
        "ms-azuretools.vscode-containers",
        "jebbs.plantuml"
      ]
    }
  },
  "remoteUser": "container-user"
}
Enter fullscreen mode Exit fullscreen mode

Dockerfile.omnia

# Use a stable version of Alpine as the base image
FROM alpine:3.21.0

# Set up the working directory
WORKDIR /workspace

# Set environment variables
ENV HOME_DIR="/home/container-user"
# ENV LV_BRANCH="release-1.4/neovim-0.9"
ENV PATH="$PATH:$HOME_DIR/.local/bin"

# Install dependencies
RUN apk update && \
    apk add --no-cache \
    python3 \
    py3-pip \
    gcc \
    musl-dev \
    python3-dev \
    libffi-dev \
    openssl-dev \
    cargo \
    make \
    yarn \
    git \
    openssh \
    neovim \
    neovim-doc \
    xclip \
    ripgrep \
    alpine-sdk \
    dotnet9-sdk \
    bash \
    zsh \
    tree \
    stow \
    unzip \
    nushell \
    tmux \
    grep \
    jq \
    curl \
    nodejs \
    npm \
    sudo \
    libc6-compat  # Install if needed for compatibility with Elm binaries

# Configuring Elm version
ARG ELM_VERSION=latest-0.19.1
ARG ELM_TEST_VERSION=latest-0.19.1
ARG ELM_FORMAT_VERSION=latest-0.19.1

# This Dockerfile adds a non-root user with sudo access.
ARG USERNAME=container-user
ARG USER_UID=1000
ARG USER_GID=$USER_UID

# Add a non-root user and group
RUN addgroup -S $USERNAME && \
    adduser -S $USERNAME -G $USERNAME --shell /bin/sh

# Install Elm using the provided method, elm-test and elm-format via npm
RUN export DEBIAN_FRONTEND=noninteractive && \
    # Install Elm binary
    curl -L -o elm.gz https://github.com/elm/compiler/releases/download/0.19.1/binary-for-linux-64-bit.gz && \
    gunzip elm.gz && \
    chmod +x elm && \
    mv elm /usr/local/bin/elm && \
    # Install elm-test and elm-format via npm
    npm install --global \
        elm-test@${ELM_TEST_VERSION} \
        elm-format@${ELM_FORMAT_VERSION} \
        elm-watch@beta && \
    # [Optional] Update UID/GID if needed
    if [ "$USER_GID" != "1000" ] || [ "$USER_UID" != "1000" ]; then \
        groupmod --gid $USER_GID $USERNAME && \
        usermod --uid $USER_UID --gid $USER_GID $USERNAME && \
        chown -R $USER_UID:$USER_GID /home/$USERNAME; \
    fi && \
    # Create the elm cache directory where we can mount a volume
    mkdir /home/$USERNAME/.elm && \
    chown $USERNAME:$USERNAME /home/$USERNAME/.elm && \
    # Create the .azure directory
    mkdir -p /home/container-user/.azure && \
    chown $USERNAME:$USERNAME /home/$USERNAME/.azure

ENV ENV=/home/$USERNAME/.profile

USER $USERNAME
RUN sh -c "$(curl -fsSL https://raw.githubusercontent.com/ohmyzsh/ohmyzsh/master/tools/install.sh)" || true
RUN git clone --depth=1 https://github.com/romkatv/powerlevel10k.git /home/$USERNAME/.oh-my-zsh/custom/themes/powerlevel10k

RUN dotnet tool install --global csharp-ls
ENV PATH="$PATH:~/.dotnet/tools"
USER root

ENV PATH="/opt/venv/bin:$PATH"
Enter fullscreen mode Exit fullscreen mode

docker-compose.yml

services:
  dev:
    build:
      context: .
      dockerfile: Dockerfile.omnia

    volumes:
      # 'cached' optimizes mount performance on macOS/Windows.
      - ../..:/workspace:cached
      - my-app-elm-devcontainer:/home/container-user/.elm
    command: sleep infinity
    networks:
      - internal
  nginx:
    image: nginx:alpine
    container_name: my-app_nginx
    ports:
     - "80:80"
     - "443:443"
     - "8314:80"
    networks:
      - internal
    volumes:
      - ./nginx.conf:/etc/nginx/nginx.conf:ro
      - ./ssl:/etc/nginx/ssl:ro
    extra_hosts:
      - "host.docker.internal:host-gateway"
    depends_on:
      - dev
      - squidex
  mongo:
    image: "mongo:6"
    volumes:
      - my-app_mongo_data:/data/db
    networks:
      - internal
    restart: unless-stopped
  squidex:
    image: "squidex/squidex:7"
    ports:
      - "8376:5000"
    environment:
      - URLS__BASEURL=https://squidex.my-app.dk
      - IDENTITY__ALLOWHTTPSCHEME=false
      - EVENTSTORE__MONGODB__CONFIGURATION=mongodb://mongo
      - STORE__MONGODB__CONFIGURATION=mongodb://mongo
      - IDENTITY__ADMINEMAIL=sukkerfrit@gmail.com
      - IDENTITY__ADMINPASSWORD=Lucas2007!
      - ASPNETCORE_URLS=http://+:5000
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:5000/healthz"]
      start_period: 60s
    depends_on:
      - mongo
    volumes:
      - my-app_squidex_assets:/app/Assets
    networks:
      - internal
    restart: unless-stopped

volumes:
  my-app-elm-devcontainer:
  my-app_squidex_assets:
  my-app_mongo_data:

networks:
  internal:
    driver: bridge
Enter fullscreen mode Exit fullscreen mode

And now for the quite important nginx.conf:

worker_processes 1;
events {
    worker_connections 1024;
}

http {
    include       /etc/nginx/mime.types;
    default_type  application/octet-stream;
    sendfile        on;
    keepalive_timeout  65;

    # Define resolver to handle host.docker.internal
    resolver 127.0.0.11;

    server {
        listen 80;
        server_name localhost my-app.dk;

        location /api/ {
            set $backend_upstream host.docker.internal:5130;
            rewrite ^/api/(.*)$ /$1 break;
            proxy_pass http://$backend_upstream;
            proxy_http_version 1.1;
            proxy_set_header Upgrade $http_upgrade;
            proxy_set_header Connection 'upgrade';
            proxy_set_header Host $host;
            proxy_cache_bypass $http_upgrade;
        }

        location /cms/ {
          set $backend_upstream host.docker.internal:5140;
          rewrite ^/cms/(.*)$ /$1 break;
          proxy_pass http://$backend_upstream;
          proxy_http_version 1.1;
          proxy_set_header Upgrade $http_upgrade;
          proxy_set_header Connection 'upgrade';
          proxy_set_header Host $host;
          proxy_cache_bypass $http_upgrade;
        }
        # Proxy frontend requests to Elm dev server
        location / {
            set $frontend_upstream host.docker.internal:3033;
            proxy_pass http://$frontend_upstream;
            proxy_http_version 1.1;
            proxy_set_header Upgrade $http_upgrade;
            proxy_set_header Connection 'upgrade';
            proxy_set_header Host $host;
            proxy_cache_bypass $http_upgrade;
            sub_filter '</head>' '<meta name="environment-name" content="local" /></head>';
            sub_filter_once on;
            # Only apply sub_filter to index.html
            # sub_filter_types text/html;
        }

        location = /robots.txt {
            set $frontend_upstream host.docker.internal:3033;
            proxy_pass http://$frontend_upstream/robots.txt;
            proxy_http_version 1.1;
            proxy_set_header Host $host;
        }

        location = /humans.txt {
            set $frontend_upstream host.docker.internal:3033;
            proxy_pass http://$frontend_upstream/humans.txt;
            proxy_http_version 1.1;
            proxy_set_header Host $host;
        }
    }
    server {
        listen 80;
        server_name squidex.my-app.dk;
        return 301 https://$host$request_uri;
    }

    server {
        listen 443 ssl;
        server_name squidex.my-app.dk;

        ssl_certificate /etc/nginx/ssl/squidex.crt;
        ssl_certificate_key /etc/nginx/ssl/squidex.key;
        ssl_protocols TLSv1.2 TLSv1.3;

        location / {
            proxy_pass http://squidex:5000;
            proxy_http_version 1.1;
            proxy_set_header Host $host;
            proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
            proxy_set_header X-Forwarded-Proto $scheme;
            proxy_set_header X-Forwarded-Host $host;

            # WebSocket support
            proxy_set_header Upgrade $http_upgrade;
            proxy_set_header Connection 'upgrade';

            # Authentication flows
            proxy_cookie_path / /;
        }
    }
}
Enter fullscreen mode Exit fullscreen mode

We are not done yet!

You'll need to:

  1. Create your own certs (.devcontainer/ssl/...)
  2. Update your hosts file (/ect/hosts)
  3. Remove or add your own versions of the app's for /api/ and /cms/

This should get you up and running with the basics of Squidex!

Security /cms/

I just create a wrapper/proxy for the Squidex api. This is done in order to keep the Client Secret - well secret. In production I use the role Reader for public stuff like Blog's, faq's etc.

If you want the code for the proxy/wrapper do write me.

Testing the setup with custom domain name

From your host machine eg. run:

curl -v http://my-app.xyz/cms/proxy/api/content/my-app/blog

curl -v -k https://squidex.my-app.xyz/squidex/app
Enter fullscreen mode Exit fullscreen mode

Tust me bro!

Make your host machines browsers trust your self-signed cert for the test domain name

On Mac:

  1. Open Keychain Access
  2. I used 'login' as Default Keychain
  3. File -> Import Items
  4. Import the created cert
  5. Set the trust level (Double click on the file)

Preparing for Production

When we have published all our containers we are ready to create yet another docker-compose file. This one is for testing the entire system as production like as possible.
That means we will be setting up:

  1. A completely new docker-compose.my-app.yml
  2. A completely revised nginx.conf
  3. Create new a certificate just for this test (Could be omitted)

Create a Certificate for multiple domain names

.... Coming soon ....

Comments 0 total

    Add comment