Forem: Edimar Cardoso

Configurando Caddy: Arquivos Estáticos e Autenticação Básica atrás de um Load Balancer

Edimar Cardoso — Thu, 03 Oct 2024 19:09:11 +0000

O Caddy server tem se mostrado um projeto muito promissor. Além de ser rápido, tem muitas funcionalidades "built-in" que facilitam muito a configuração. Um dos exemplos é a emissão automática de certificados SSL. Além disso, é muito fácil configurar um serviço utilizando ele.

Esta semana, precisei criar um serviço para publicar arquivos estáticos. Ao tentar fazer isto com a configuração padrão dele, notei que não seria possível usar a configuração padrão por ter um cenário um pouco diferente.

No meu cenário, o serviço iria rodar atrás de um load balancer na zCloud que já é responsável por gerar os certificados e fazer a terminação do TLS/SSL. A configuração padrão gerou problemas pois não deveria gerar certificado SSL, apenas servir os arquivos na porta HTTP padrão.

Além disso, havia outra particularidade: precisava de um endpoint de health check com acesso público, enquanto todo o restante precisava ser bloqueado utilizando autenticação padrão "Basic Auth".

A seguir, o arquivo utilizado para fazer isto de uma forma bem simples:

{
  auto_https off
}
:8080 {
    route /_health* {
        respond 200
    }
    route {
        basic_auth / {
            USER_NAME HASH_PASSWORD
        }
        root * /var/www/static
        file_server
    }
}

Explicando um pouco sobre a configuração:

Desabilitando SSL

auto_https off

Desabilita a emissão automática de certificado e desabilita o redirecionamento para HTTPS.

Porta

:8080 {
# ...

Porta que será aberta para receber conexões.

Health check

    route /_health* {
        respond 200
    }

Rota para acesso ao health check com acesso público.

Arquivos estáticos com autenticação

    route {
        basic_auth / {
            USER_NAME HASH_PASSWORD
        }
        root * /var/www/static
        file_server
    }

Esta parte da configuração irá receber todo restante das requests, interceptar as requisições e forçar um login, caso o usuário não esteja logado, e servir os arquivos do diretório /var/www/static.

O valor USER_NAME é o nome do usuário que será usado para autenticar.
O valor HASH_PASSWORD é o hash gerado pelo CLI do Caddy com base na senha definida. Para gerar este valor, basta seguir as instruções na documentação oficial basic_auth.

Conclusão

Esta configuração do Caddy Server oferece uma solução elegante para servir arquivos estáticos com autenticação, ao mesmo tempo que permite um endpoint de health check público. A flexibilidade e simplicidade do Caddy tornam-no uma excelente escolha para diversos cenários de deploy.

Using Caddy to Serve Static Files Behind a Load Balancer

Edimar Cardoso — Thu, 03 Oct 2024 19:07:34 +0000

Caddy server has proven to be a very promising project. Not only is it fast, but it also has many built-in features that greatly simplify configuration. One example is the automatic issuance of SSL certificates. Moreover, it's very easy to set up a service using Caddy.

This week, I needed to create a service to publish static files. When trying to do this with Caddy's default configuration, I noticed it wouldn't be possible due to a slightly different scenario.

In my scenario, the service would run behind a load balancer at zCloud that's already responsible for generating certificates and handling TLS/SSL termination. The default configuration caused issues because it shouldn't generate an SSL certificate, but only serve files on the default HTTP port.

Additionally, there was another particularity: I needed a health check endpoint with public access, while everything else needed to be blocked using standard "Basic Auth" authentication.

Here's the file used to accomplish this in a simple way:

{
  auto_https off
}
:8080 {
    route /_health* {
        respond 200
    }
    route {
        basic_auth / {
            USER_NAME HASH_PASSWORD
        }
        root * /var/www/static
        file_server
    }
}

Let's break down the configuration:

Disabling SSL

auto_https off

This disables automatic certificate issuance and disables redirection to HTTPS.

Port

:8080 {
# ...

This specifies the port that will be opened to receive connections.

Health check

    route /_health* {
        respond 200
    }

This route provides public access to the health check endpoint.

Static files with authentication

    route {
        basic_auth / {
            USER_NAME HASH_PASSWORD
        }
        root * /var/www/static
        file_server
    }

This part of the configuration will receive all other requests, intercept them and force a login if the user is not logged in, and serve files from the /var/www/static directory.

The USER_NAME value is the username that will be used for authentication.
The HASH_PASSWORD value is the hash generated by the Caddy CLI based on the defined password. To generate this value, simply follow the instructions in the official basic_auth documentation.

Conclusion

This Caddy Server configuration offers an elegant solution for serving static files with authentication while allowing a public health check endpoint. Caddy's flexibility and simplicity make it an excellent choice for various deployment scenarios.

Migrating from shell script to "Bun script"

Edimar Cardoso — Fri, 27 Sep 2024 21:58:59 +0000

When working on a project focused on process automation and infrastructure at zCloud, we frequently encounter the need to create multiple functions to perform validations and common processes. Everything works fine when using only one operating system, but the situation becomes complicated when more than one system is involved.

In our case, most of the development happens on Linux, but we also need to ensure compatibility with macOS. This often results in code incompatibilities.

To address this issue, we are migrating our shell script functions to JavaScript files, using Bun as the interpreter. We chose Bun because it provides a simple way to run commands like a shell through its Shell API functionality.

Below is an example of a function we use to check for any code changes before applying infrastructure modifications.

Shell script code:

function zc_check_pristine_git() {
    if [ "$ZC_CURRENT_ENV" = "staging" ] || [ "$ZC_CURRENT_ENV" = "dev" ]; then
      return 0
    fi

    local not_pristine=0
    local modified_files=""

    # Check for staged but uncommitted changes
    staged_changes=$(git diff --name-only --cached)
    if [ -n "$staged_changes" ]; then
        not_pristine=1
        modified_files+="Staged changes:\n$staged_changes"
    fi

    # Check for unstaged changes
    unstaged_changes=$(git diff --name-only)
    if [ -n "$unstaged_changes" ]; then
        not_pristine=1
        modified_files+="Unstaged changes:\n$unstaged_changes"
    fi

    # Check for untracked files
    untracked_files=$(git ls-files --others --exclude-standard)
    if [ -n "$untracked_files" ]; then
        not_pristine=1
        modified_files+="Untracked files:\n$untracked_files"
    fi

    # Check if the current branch is ahead of the remote
    ahead_commits=$(git log @{u}.. --oneline)
    if [ -n "$ahead_commits" ]; then
        not_pristine=1
        modified_files+="Commits ahead of the remote:\n$ahead_commits\n\n"
    fi

    if [ $not_pristine -eq 1 ]; then
        echo -e "$modified_files"
        return 1
    fi

    return 0
}

To convert this code to JavaScript, we created a file named zc_check_pristine_git in the project’s bin directory (which is already in the PATH) with the following content:

#!/usr/bin/env bun
// @language JavaScript

import { checkPristineGit } from '../js/helpers/helpers.js';

await checkPristineGit({ currentEnv: process.env.ZC_CURRENT_ENV });

We used the shebang #!/usr/bin/env bun to indicate that we are using Bun as the interpreter.

We added the comment // @language JavaScript so that the IDE recognizes the file as JavaScript (we mainly use Jetbrains tools).

Then, we imported the function that will actually be executed.

Implementation of the function converted from shell to JavaScript:

export const checkPristineGit = async ({ currentEnv }) => {
  exitOnError(() => {
    notEmpty(currentEnv, 'currentEnv is required');
  });
  if (['staging', 'dev'].includes(currentEnv)) {
    return;
  }

  let notPristine = 0;
  let modifiedFiles = '';

  // Check for staged but uncommitted changes
  const stagedChanges = await $`git diff --name-only --cached`.text();
  if (stagedChanges !== '') {
    notPristine = 1;
    modifiedFiles += `Staged changes:\n${stagedChanges}`;
  }

  // Check for unstaged changes
  const unstagedChanges = await $`git diff --name-only`.text();
  if (unstagedChanges !== '') {
    notPristine = 1;
    modifiedFiles += `Unstaged changes:\n${unstagedChanges}`;
  }

  // Check for untracked files
  const untrackedFiles = await $`git ls-files --others --exclude-standard`.text();
  if (untrackedFiles !== '') {
    notPristine = 1;
    modifiedFiles += `Untracked files:\n${untrackedFiles}`;
  }

  // Check if the current branch is ahead of the remote
  const aheadCommits = await $`git log @{u}.. --oneline`.text();
  if (aheadCommits !== '') {
    notPristine = 1;
    modifiedFiles += `Commits ahead of the remote:\n${aheadCommits}`;
  }

  if (notPristine) {
    console.warn('Error: You can only apply changes in production environments if the repository is in a pristine state.');
    console.warn(modifiedFiles);
    process.exit(1);
  }
};

This way, we have standardized JavaScript code that will be executed like a shell script.

There are calls to functions (exitOnError, notEmpty) that are not implemented in the provided example.