@fluxup/installer 1.3.0

package/LICENSE

@@ -0,0 +1,21 @@
+Copyright (c) 2026
+Diovani Bernardi da Motta
+
+All rights reserved.
+
+This software and associated documentation files (the "Software") are the
+exclusive property of the Authors.
+
+No permission is granted to use, copy, modify, merge, publish, distribute,
+sublicense, and/or sell copies of the Software, in whole or in part, without
+explicit prior written permission from the Authors.
+
+The Software may not be used for commercial purposes without a separate
+written commercial agreement signed by the Authors.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN
+ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -0,0 +1,154 @@
+## Visao geral
+
+Este repositório centraliza o processo de instalação da plataforma FluxUp em servidores Docker on-premises.
+Contém a CLI de instalação interativa (`npx @fluxup/installer`), o `docker-compose.yml` baseado em imagens pré-publicadas no GHCR, e a configuração de nginx que serve o frontend e faz proxy para os serviços internos.
+
+> Contexto de negócio completo: [github.com/fluxup-platform/profile](https://github.com/fluxup-platform/profile/blob/main/README.md)
+
+## Tecnologias
+
+| Tecnologia | Versão mínima | Papel |
+|---|---|---|
+| Node.js | 18 | Runtime da CLI npx |
+| Docker Engine | 20.10 | Execução dos containers |
+| Docker Compose | v2 | Orquestração dos serviços |
+| AWS SDK for JS | v3 | Download do S3 e acesso ao Secrets Manager |
+| nginx | alpine | Reverse proxy e servidor de arquivos estáticos |
+
+---
+
+## Arquitetura
+
+O instalador opera em 10 etapas sequenciais:
+
+1. **Preflight** — verifica `docker` e `docker compose` v2 no servidor
+2. **Wizard** — coleta variáveis de configuração via prompts interativos (DB, rede, S3, GHCR)
+3. **SSM Parameter Store** — lê ARNs de IAM roles, URLs de filas SQS e nome da tabela DynamoDB via `GetParametersByPath`; nenhuma credencial estática é coletada
+4. **Secrets Manager** — busca o token GHCR no AWS Secrets Manager (em memória, nunca em disco)
+5. **GHCR Login** — `docker login ghcr.io --password-stdin` com o token obtido
+6. **Download S3** — baixa o `docker-compose.yml` template do bucket S3 via SDK
+7. **Render compose** — substitui os placeholders SSM (`${AWS_STS_BROKER_ROLE_ARN}` etc.) por valores literais no YAML; `${DB_*}`, `${NGINX_*}` permanecem para resolução pelo Docker Compose
+8. **Geração do .env** — cria `<dir>/.env` com permissão `0600` (apenas config do wizard; sem ARNs ou credenciais AWS)
+9. **Pull + Up** — `docker compose pull` seguido de `docker compose up -d`
+10. **Status** — exibe containers ativos e URLs de acesso
+
+O nginx embute o build do Angular frontend como imagem GHCR. O servidor on-premises não precisa de código-fonte — apenas Docker.
+
+---
+
+## Como executar a instalação
+
+### Pré-requisitos no servidor
+
+- Docker Engine ≥ 20.10 instalado e em execução
+- Docker Compose v2 disponível (`docker compose version`)
+- Node.js ≥ 18 disponível no `PATH` (apenas para o npx — pode ser removido após instalar)
+- Acesso à internet: GHCR, bucket S3 e AWS Secrets Manager
+
+### Execução
+
+```bash
+npx @fluxup/installer
+```
+
+O wizard guiará pela configuração de todas as variáveis necessárias.
+
+### Flags disponíveis
+
+| Flag | Descrição |
+|------|-----------|
+| `--dir <path>` | Diretório de instalação (padrão: `./fluxup`) |
+| `--non-interactive` | Lê variáveis já exportadas no shell — útil para CI/automação |
+| `--no-pull` | Pula o `docker compose pull` |
+
+### Modo não-interativo (CI/automação)
+
+```bash
+export GHCR_USERNAME="Fluxup Deploy Bot"
+export GHCR_SECRET_NAME="fluxup/ghcr-token"
+export IMAGE_TAG="1.4.3"
+export S3_BUCKET="fluxup-installer"
+export S3_KEY="releases/v1.4.3/docker-compose.yml"
+export AWS_REGION="us-east-1"
+export AWS_SSM_PREFIX="/fluxup"
+# DB e rede
+export DB_NAME="fluxup"
+export DB_USERNAME="fluxup"
+export DB_PASSWORD="..."
+export DB_PORT="5432"
+export DB_BIND_HOST="127.0.0.1"
+export JPA_DDL_AUTO="update"
+export NGINX_PORT="80"
+export BACKEND_API_TIMEOUT="5000"
+
+# Credenciais AWS via instance profile (IMDSv2) — não definir AWS_ACCESS_KEY_ID/SECRET
+npx @fluxup/installer --non-interactive --dir /opt/fluxup
+```
+
+---
+
+## Configuração do secret GHCR no AWS Secrets Manager
+
+Crie um secret com valor JSON:
+
+```json
+{ "token": "ghp_..." }
+```
+
+O nome do secret é configurado via `GHCR_SECRET_NAME` (padrão: `fluxup/ghcr-token`).
+O token **nunca** é armazenado em disco — apenas em memória durante o login.
+
+---
+
+## Estrutura do repositório
+
+```
+compose/docker-compose.yml          — compose baseado em imagens (fonte; CI publica no S3)
+nginx/Dockerfile                    — build nginx + Angular frontend (usado só pelo CI)
+nginx/nginx.conf                    — configuração do nginx (proxy + SPA fallback)
+bin/cli.js                          — entrypoint da CLI
+src/
+  preflight.js                      — verifica pré-requisitos Docker
+  wizard.js                         — prompts interativos agrupados
+  env.schema.js                     — definição declarativa de variáveis do wizard
+  aws-resources.js                  — lê ARNs e URLs do AWS SSM Parameter Store
+  compose-renderer.js               — substitui valores SSM diretamente no YAML
+  secrets.js                        — busca token GHCR no AWS Secrets Manager
+  ghcr.js                           — docker login via --password-stdin
+  s3.js                             — download do compose do bucket S3
+  env.js                            — geração do .env (config do wizard)
+  docker.js                         — docker compose pull / up / ps
+.github/workflows/
+  publish-nginx.yml                 — publica ghcr.io/fluxup-platform/fluxup-nginx:<ver>
+  upload-compose.yml                — sobe compose no S3 em cada release tag
+```
+
+---
+
+## Release
+
+Em cada tag `vX.Y.Z`, os workflows CI executam automaticamente:
+
+1. `publish-nginx.yml` — builda o nginx com o frontend Angular e publica `ghcr.io/fluxup-platform/fluxup-nginx:X.Y.Z` no GHCR
+2. `upload-compose.yml` — sobe `compose/docker-compose.yml` para `s3://<bucket>/releases/X.Y.Z/docker-compose.yml`
+
+O instalador então usa `IMAGE_TAG=X.Y.Z` e `S3_KEY=releases/X.Y.Z/docker-compose.yml` para instalar a versão correta.
+
+---
+
+## Contribuição
+
+1. Leia o [CONTRIBUTING.md](CONTRIBUTING.md) antes de começar.
+2. Crie uma branch de feature: `git checkout -b feature/descricao-curta`.
+3. Valide localmente: `npm install && node bin/cli.js --help`.
+4. Abra um pull request com descrição objetiva das mudanças.
+
+---
+
+## Autores
+
+- [Diovani Motta](https://github.com/diovanibmotta)
+
+## Contato
+
+Dúvidas ou sugestões: [contato@fluxup.com.br](mailto:contato@fluxup.com.br)

package/bin/cli.js

@@ -0,0 +1,171 @@
+#!/usr/bin/env node
+/**
+ * fluxup-installer — FluxUp on-premises Docker installation CLI.
+ *
+ * Usage:
+ *   npx @fluxup/installer
+ *   npx @fluxup/installer --dir /opt/fluxup
+ *   npx @fluxup/installer --non-interactive   (reads env vars already exported in the shell)
+ *   npx @fluxup/installer --no-pull           (skips docker compose pull)
+ *
+ * AWS authentication:
+ *   The installer uses the default AWS credential chain (instance profile / environment /
+ *   shared credentials file). No static AWS credentials are collected or stored.
+ *   The host must have an IAM role with permissions to read from SSM Parameter Store,
+ *   S3 (compose bucket), and Secrets Manager (GHCR token secret).
+ */
+
+import { join, resolve } from 'node:path';
+import { mkdirSync } from 'node:fs';
+import * as p from '@clack/prompts';
+import pc from 'picocolors';
+
+import { preflight } from '../src/preflight.js';
+import { runWizard } from '../src/wizard.js';
+import { resolveAwsResources } from '../src/aws-resources.js';
+import { fetchGhcrToken } from '../src/secrets.js';
+import { loginGhcr } from '../src/ghcr.js';
+import { downloadCompose } from '../src/s3.js';
+import { writeEnvFile } from '../src/env.js';
+import { renderCompose } from '../src/compose-renderer.js';
+import { pullImages, upServices, showStatus } from '../src/docker.js';
+
+// ─── Flag parsing ─────────────────────────────────────────────────────────────
+const args = process.argv.slice(2);
+const flags = {
+  dir: args[args.indexOf('--dir') + 1] ?? './fluxup',
+  nonInteractive: args.includes('--non-interactive'),
+  noPull: args.includes('--no-pull'),
+};
+
+const installDir = resolve(flags.dir);
+
+// ─── Main ────────────────────────────────────────────────────────────────────
+async function main() {
+  console.log('');
+  console.log(pc.bgBlue(pc.white(' FluxUp Install ')));
+  console.log(pc.dim(`Install directory: ${installDir}\n`));
+
+  // 1. Preflight
+  p.log.step('Checking prerequisites...');
+  await preflight();
+
+  // 2. Wizard (or read from existing env vars in --non-interactive mode)
+  let answers;
+  if (flags.nonInteractive) {
+    p.log.info('Non-interactive mode: reading environment variables from shell.');
+    answers = Object.fromEntries(
+      process.env
+        ? Object.entries(process.env).filter(([k]) => k.match(/^(GHCR|IMAGE|S3|AWS|DB|JPA|NGINX|BACKEND)/))
+        : []
+    );
+  } else {
+    answers = await runWizard();
+  }
+
+  // 3. Resolve AWS resource identifiers from SSM Parameter Store
+  p.log.step('Resolving AWS resource identifiers from SSM Parameter Store...');
+  let awsResources;
+  try {
+    awsResources = await resolveAwsResources({
+      prefix: answers.AWS_SSM_PREFIX,
+      region: answers.AWS_REGION,
+    });
+  } catch (err) {
+    p.log.error(`Failed to resolve AWS resources from SSM: ${err.message}`);
+    p.log.warn(
+      'Ensure the host has an IAM role with ssm:GetParametersByPath permission\n' +
+      `and that all parameters exist under: ${answers.AWS_SSM_PREFIX}`
+    );
+    process.exit(1);
+  }
+
+  // 4. Fetch GHCR token from AWS Secrets Manager (in-memory only — never written to disk)
+  p.log.step('Fetching GHCR token from AWS Secrets Manager...');
+  let ghcrToken;
+  try {
+    ghcrToken = await fetchGhcrToken({
+      secretName: answers.GHCR_SECRET_NAME,
+      region: answers.AWS_REGION,
+    });
+    p.log.success('GHCR token retrieved from Secrets Manager.');
+  } catch (err) {
+    p.log.error(`Failed to fetch GHCR token: ${err.message}`);
+    p.log.warn('Check the IAM role permissions and the secret name (GHCR_SECRET_NAME).');
+    process.exit(1);
+  }
+
+  // 5. GHCR login
+  p.log.step('Authenticating with GHCR...');
+  try {
+    await loginGhcr({ username: answers.GHCR_USERNAME, token: ghcrToken });
+  } catch (err) {
+    p.log.error(`GHCR login failed: ${err.message}`);
+    process.exit(1);
+  }
+
+  // Discard token from memory
+  ghcrToken = null;
+
+  // 6. Create install directory and download docker-compose.yml from S3
+  mkdirSync(installDir, { recursive: true });
+  const composePath = join(installDir, 'docker-compose.yml');
+
+  p.log.step('Downloading docker-compose.yml from S3...');
+  try {
+    await downloadCompose({
+      bucket: answers.S3_BUCKET,
+      key: answers.S3_KEY,
+      region: answers.S3_REGION || answers.AWS_REGION,
+      destPath: composePath,
+    });
+  } catch (err) {
+    p.log.error(`Failed to download compose from S3: ${err.message}`);
+    process.exit(1);
+  }
+
+  // 7. Inline SSM-resolved values directly into docker-compose.yml
+  //    ARNs, queue URLs, and table names are baked in as literal values so the compose
+  //    file is self-contained. ${DB_*}, ${NGINX_*} etc. remain as placeholders resolved
+  //    from .env at runtime.
+  p.log.step('Injecting SSM values into docker-compose.yml...');
+  try {
+    renderCompose(composePath, awsResources);
+  } catch (err) {
+    p.log.error(`Failed to inject SSM values into docker-compose.yml: ${err.message}`);
+    p.log.warn('Check for placeholder/key drift between compose template and SSM mapping.');
+    process.exit(1);
+  }
+
+  // 8. Write .env (wizard-collected config only — SSM values already inlined above)
+  p.log.step('Generating .env file...');
+  const envPath = writeEnvFile(installDir, answers);
+
+  // 9. Pull + Up
+  try {
+    if (!flags.noPull) {
+      await pullImages(composePath, envPath);
+    }
+    await upServices(composePath, envPath);
+  } catch (err) {
+    p.log.error(`Docker Compose failed: ${err.message}`);
+    process.exit(1);
+  }
+
+  // 10. Post-install
+  await showStatus(composePath, envPath);
+
+  const port = answers.NGINX_PORT ?? '80';
+  console.log('');
+  p.outro(
+    pc.green('✔ FluxUp installed successfully!') +
+    `\n\n  Frontend: ${pc.cyan(`http://<server>:${port}/`)}\n` +
+    `  API:      ${pc.cyan(`http://<server>:${port}/api/`)}\n` +
+    `  BFF:      ${pc.cyan(`http://<server>:${port}/bff/`)}\n`
+  );
+}
+
+main().catch((err) => {
+  console.error(pc.red('\nUnexpected error:'), err);
+  process.exit(1);
+});

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "@fluxup/installer",
+  "version": "1.3.0",
+  "description": "FluxUp on-premises Docker installation CLI",
+  "type": "module",
+  "bin": {
+    "fluxup-installer": "./bin/cli.js"
+  },
+  "files": [
+    "bin/",
+    "src/"
+  ],
+  "scripts": {
+    "lint": "node --check bin/cli.js src/*.js",
+    "check:exact-deps": "node scripts/check-exact-deps.js",
+    "build": "npm run lint && npm run check:exact-deps",
+    "semantic-release": "semantic-release"
+  },
+  "dependencies": {
+    "@aws-sdk/client-s3": "3.1063.0",
+    "@aws-sdk/client-secrets-manager": "3.1063.0",
+    "@aws-sdk/client-ssm": "3.1063.0",
+    "@clack/prompts": "0.9.1",
+    "execa": "9.6.1",
+    "picocolors": "1.1.1"
+  },
+  "devDependencies": {
+    "@semantic-release/changelog": "6.0.3",
+    "@semantic-release/git": "10.0.1",
+    "@semantic-release/github": "10.3.5",
+    "@semantic-release/npm": "12.0.2",
+    "conventional-changelog-conventionalcommits": "9.3.1",
+    "semantic-release": "24.2.9"
+  },
+  "engines": {
+    "node": ">=18",
+    "npm": ">=7"
+  },
+  "license": "UNLICENSED",
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/aws-resources.js

@@ -0,0 +1,74 @@
+import { SSMClient, GetParametersByPathCommand } from '@aws-sdk/client-ssm';
+import pc from 'picocolors';
+
+/**
+ * Maps SSM parameter paths (relative to the prefix) to .env variable names.
+ * Infrastructure must publish these parameters before running the installer.
+ */
+const SSM_PARAM_MAP = {
+  '/iam/sts-broker-role-arn':            'AWS_STS_BROKER_ROLE_ARN',
+  '/iam/secretsmanager-reader-role-arn': 'AWS_SECRETSMANAGER_READER_ROLE_ARN',
+  '/iam/dynamodb-role-arn':              'AWS_DYNAMODB_DAILY_JOBS_ROLE_ARN',
+  '/iam/sqs-consumer-role-arn':          'AWS_SQS_CONSUMER_ROLE_ARN',
+  '/iam/sqs-publisher-role-arn':         'AWS_SQS_PUBLISHER_ROLE_ARN',
+  '/dynamodb/daily-jobs-table':          'AWS_DAILY_JOBS_TABLE',
+  '/sqs/daily-request-queue-url':        'AWS_DAILY_REQUEST_QUEUE_URL',
+  '/sqs/daily-response-queue-url':       'AWS_DAILY_RESPONSE_QUEUE_URL',
+  '/sqs/daily-dlq-url':                  'AWS_DAILY_DLQ_URL',
+};
+
+/**
+ * Resolves all required AWS resource identifiers from SSM Parameter Store.
+ * Uses the default AWS credential chain — no explicit credentials required.
+ * On EC2, this resolves via the instance profile (IMDSv2).
+ *
+ * @param {object} opts
+ * @param {string} opts.prefix  SSM path prefix (e.g. '/fluxup')
+ * @param {string} opts.region  AWS region
+ * @returns {Promise<Record<string, string>>} Map of env-var names to resolved values
+ */
+export async function resolveAwsResources({ prefix, region }) {
+  const client = new SSMClient({ region });
+  const path = prefix.endsWith('/') ? prefix.slice(0, -1) : prefix;
+
+  console.log(pc.dim(`  Fetching SSM parameters under ${path}/...`));
+
+  const resolved = {};
+  let nextToken;
+
+  do {
+    const { Parameters, NextToken } = await client.send(
+      new GetParametersByPathCommand({
+        Path: path,
+        Recursive: true,
+        WithDecryption: true,
+        NextToken: nextToken,
+      })
+    );
+
+    for (const param of Parameters ?? []) {
+      const relative = param.Name.slice(path.length);
+      const envKey = SSM_PARAM_MAP[relative];
+      if (envKey) {
+        resolved[envKey] = param.Value;
+      }
+    }
+
+    nextToken = NextToken;
+  } while (nextToken);
+
+  const missing = Object.entries(SSM_PARAM_MAP)
+    .filter(([, envKey]) => !resolved[envKey])
+    .map(([ssmPath, envKey]) => `${path}${ssmPath} → ${envKey}`);
+
+  if (missing.length > 0) {
+    throw new Error(
+      `The following SSM parameters were not found:\n` +
+      missing.map((m) => `  • ${m}`).join('\n') +
+      `\n\nEnsure infrastructure has published all required parameters under ${path}/`
+    );
+  }
+
+  console.log(pc.green('✔') + ` Resolved ${Object.keys(resolved).length} AWS resource identifiers from SSM.`);
+  return resolved;
+}

package/src/compose-renderer.js

@@ -0,0 +1,41 @@
+import { readFileSync, writeFileSync } from 'node:fs';
+import pc from 'picocolors';
+
+/**
+ * Substitutes SSM-resolved values directly into the compose YAML.
+ *
+ * Only SSM keys are inlined — DB credentials, ports, and other wizard-collected
+ * vars remain as ${VAR} placeholders resolved by Docker Compose from .env at runtime.
+ *
+ * This makes the compose file self-contained for AWS resource identifiers:
+ * reading the file shows the actual ARNs/URLs without needing to cross-reference .env.
+ *
+ * @param {string}                  composePath  Path to the docker-compose.yml on disk
+ * @param {Record<string, string>}  ssmValues    Map of env-var name → resolved value from SSM
+ */
+export function renderCompose(composePath, ssmValues) {
+  let content = readFileSync(composePath, 'utf8');
+  const notApplied = [];
+
+  for (const [key, value] of Object.entries(ssmValues)) {
+    const token = `\${${key}}`;
+    if (!content.includes(token)) {
+      notApplied.push(key);
+      continue;
+    }
+    content = content.replaceAll(token, value);
+  }
+
+  if (notApplied.length > 0) {
+    throw new Error(
+      `Compose placeholders not found for resolved SSM keys: ${notApplied.join(', ')}`
+    );
+  }
+
+  writeFileSync(composePath, content, { encoding: 'utf8' });
+
+  console.log(
+    pc.green('✔') +
+    ` Inlined ${Object.keys(ssmValues).length} SSM values into docker-compose.yml`
+  );
+}

package/src/docker.js

@@ -0,0 +1,48 @@
+import { execa } from 'execa';
+import pc from 'picocolors';
+
+/**
+ * Runs docker compose with the given files and arguments.
+ */
+function compose(composePath, envPath, args) {
+  return execa(
+    'docker',
+    ['compose', '-f', composePath, '--env-file', envPath, ...args],
+    { stdout: 'inherit', stderr: 'inherit' }
+  );
+}
+
+/**
+ * Pulls all images declared in the compose file.
+ *
+ * @param {string} composePath
+ * @param {string} envPath
+ */
+export async function pullImages(composePath, envPath) {
+  console.log(pc.bold('\nPulling images...'));
+  await compose(composePath, envPath, ['pull']);
+  console.log(pc.green('✔') + ' Pull complete.');
+}
+
+/**
+ * Starts all services in detached mode.
+ *
+ * @param {string} composePath
+ * @param {string} envPath
+ */
+export async function upServices(composePath, envPath) {
+  console.log(pc.bold('\nStarting containers...'));
+  await compose(composePath, envPath, ['up', '-d']);
+  console.log(pc.green('✔') + ' Containers running.');
+}
+
+/**
+ * Displays container status.
+ *
+ * @param {string} composePath
+ * @param {string} envPath
+ */
+export async function showStatus(composePath, envPath) {
+  console.log(pc.bold('\nContainer status:'));
+  await compose(composePath, envPath, ['ps']);
+}

package/src/env.js

@@ -0,0 +1,46 @@
+import { writeFileSync, chmodSync } from 'node:fs';
+import { join } from 'node:path';
+import { ENV_SCHEMA } from './env.schema.js';
+import pc from 'picocolors';
+
+/**
+ * Writes the .env file to the install directory.
+ *
+ * Only schema-defined keys are written (wizard-collected values: GHCR, S3, AWS, DB, network).
+ * AWS resource identifiers (ARNs, queue URLs, table names) are NOT stored here —
+ * they are inlined directly into docker-compose.yml by compose-renderer.js at install time.
+ *
+ * The GHCR token is NOT included — fetched from Secrets Manager at runtime.
+ * AWS static credentials are NOT included — services authenticate via IAM instance profile.
+ * Permission 0600 applied (owner read-only).
+ *
+ * @param {string}                    dir      Directory where .env will be created
+ * @param {Record<string, string>}    answers  Wizard answers (schema keys only)
+ * @returns {string} Path to the created .env file
+ */
+export function writeEnvFile(dir, answers) {
+  const envPath = join(dir, '.env');
+
+  const schemaLines = ENV_SCHEMA.map((f) => `${f.key}=${answers[f.key] ?? ''}`);
+
+  const content = [
+    '# Generated by fluxup-installer — DO NOT commit',
+    '# AWS credentials are NOT stored here — services authenticate via IAM instance profile',
+    '# AWS resource identifiers (ARNs, queue URLs) are inlined in docker-compose.yml',
+    '',
+    ...schemaLines,
+    '',
+  ].join('\n');
+
+  writeFileSync(envPath, content, { encoding: 'utf8' });
+
+  try {
+    chmodSync(envPath, 0o600);
+  } catch {
+    // Windows does not support chmod — silently ignored
+  }
+
+  console.log(pc.green('✔') + ` .env created at ${envPath}`);
+
+  return envPath;
+}

package/src/env.schema.js

@@ -0,0 +1,121 @@
+/**
+ * Declarative definition of all environment variables collected by the wizard.
+ *
+ * Fields:
+ *   key      — variable name in .env
+ *   prompt   — text displayed to the user
+ *   default  — default value (string) or undefined
+ *   secret   — true = masked input
+ *   group    — visual grouping in the wizard
+ *
+ * AWS resource identifiers (ARNs, queue URLs, table names) are NOT collected here.
+ * They are resolved at install time from AWS SSM Parameter Store via aws-resources.js.
+ * AWS credentials are NOT collected — services authenticate via IAM instance profile.
+ */
+export const ENV_SCHEMA = [
+  // ─── GHCR ────────────────────────────────────────────────────────────────
+  {
+    group: 'GHCR (GitHub Container Registry)',
+    key: 'GHCR_USERNAME',
+    prompt: 'GHCR username (e.g. Fluxup Deploy Bot)',
+    default: 'Fluxup Deploy Bot',
+  },
+  {
+    group: 'GHCR (GitHub Container Registry)',
+    key: 'IMAGE_TAG',
+    prompt: 'Installer image tag used for the nginx service (e.g. 1.4.3)',
+    default: 'latest',
+  },
+  {
+    group: 'GHCR (GitHub Container Registry)',
+    key: 'GHCR_SECRET_NAME',
+    prompt: 'Name/ARN of the AWS Secrets Manager secret that holds the GHCR token',
+    default: 'fluxup/ghcr-token',
+  },
+
+  // ─── S3 ──────────────────────────────────────────────────────────────────
+  {
+    group: 'S3 (docker-compose source)',
+    key: 'S3_BUCKET',
+    prompt: 'S3 bucket name that stores docker-compose.yml',
+    default: 'fluxup-installer',
+  },
+  {
+    group: 'S3 (docker-compose source)',
+    key: 'S3_KEY',
+    prompt: 'Object key in the bucket (e.g. v1.4.3/docker-compose.yml)',
+    default: 'docker-compose.yml',
+  },
+  {
+    group: 'S3 (docker-compose source)',
+    key: 'S3_REGION',
+    prompt: 'AWS region of the S3 bucket (leave blank to use AWS_REGION)',
+    default: '',
+  },
+
+  // ─── AWS ─────────────────────────────────────────────────────────────────
+  {
+    group: 'AWS',
+    key: 'AWS_REGION',
+    prompt: 'Default AWS region',
+    default: 'us-east-1',
+  },
+  {
+    group: 'AWS',
+    key: 'AWS_SSM_PREFIX',
+    prompt: 'SSM Parameter Store prefix where AWS resource identifiers are stored',
+    default: '/fluxup',
+  },
+
+  // ─── Database ────────────────────────────────────────────────────────────
+  {
+    group: 'Database (PostgreSQL)',
+    key: 'DB_NAME',
+    prompt: 'Database name',
+    default: 'fluxup',
+  },
+  {
+    group: 'Database (PostgreSQL)',
+    key: 'DB_USERNAME',
+    prompt: 'Database username',
+    default: 'fluxup',
+  },
+  {
+    group: 'Database (PostgreSQL)',
+    key: 'DB_PASSWORD',
+    prompt: 'Database password',
+    secret: true,
+  },
+  {
+    group: 'Database (PostgreSQL)',
+    key: 'DB_PORT',
+    prompt: 'Database host port (exposed on the host machine)',
+    default: '5432',
+  },
+  {
+    group: 'Database (PostgreSQL)',
+    key: 'DB_BIND_HOST',
+    prompt: 'Host address the DB port binds to (127.0.0.1 = localhost only; 0.0.0.0 = all interfaces)',
+    default: '127.0.0.1',
+  },
+  {
+    group: 'Database (PostgreSQL)',
+    key: 'JPA_DDL_AUTO',
+    prompt: 'JPA DDL Auto (update | validate | none)',
+    default: 'update',
+  },
+
+  // ─── Network ─────────────────────────────────────────────────────────────
+  {
+    group: 'Network',
+    key: 'NGINX_PORT',
+    prompt: 'nginx HTTP port on the host',
+    default: '80',
+  },
+  {
+    group: 'Network',
+    key: 'BACKEND_API_TIMEOUT',
+    prompt: 'Backend API timeout in ms',
+    default: '5000',
+  },
+];

package/src/ghcr.js

@@ -0,0 +1,22 @@
+import { execa } from 'execa';
+import pc from 'picocolors';
+
+/**
+ * Authenticates with GHCR using docker login --password-stdin.
+ * The token stays in memory only (piped directly to the docker process).
+ *
+ * @param {object} opts
+ * @param {string} opts.username   GHCR username
+ * @param {string} opts.token      GHCR token (fetched from AWS Secrets Manager)
+ */
+export async function loginGhcr({ username, token }) {
+  console.log(pc.dim(`  docker login ghcr.io -u "${username}" --password-stdin`));
+
+  await execa('docker', ['login', 'ghcr.io', '-u', username, '--password-stdin'], {
+    input: token,
+    stdout: 'inherit',
+    stderr: 'inherit',
+  });
+
+  console.log(pc.green('✔') + ' GHCR login successful.');
+}

package/src/preflight.js

@@ -0,0 +1,41 @@
+import { execa } from 'execa';
+import pc from 'picocolors';
+
+/**
+ * Checks that docker and docker compose v2 are available.
+ * Aborts with a clear message if any prerequisite is missing.
+ */
+export async function preflight() {
+  const checks = [
+    {
+      cmd: 'docker',
+      args: ['--version'],
+      label: 'Docker',
+      hint: 'Install Docker Engine: https://docs.docker.com/engine/install/',
+    },
+    {
+      cmd: 'docker',
+      args: ['compose', 'version'],
+      label: 'Docker Compose v2',
+      hint: 'Compose v2 ships with Docker Engine >= 20.10. Update Docker.',
+    },
+  ];
+
+  let ok = true;
+
+  for (const { cmd, args, label, hint } of checks) {
+    try {
+      const { stdout } = await execa(cmd, args);
+      console.log(pc.green('✔') + ' ' + label + ' — ' + stdout.trim().split('\n')[0]);
+    } catch {
+      console.error(pc.red('✘') + ' ' + label + ' not found.');
+      console.error('  ' + pc.yellow(hint));
+      ok = false;
+    }
+  }
+
+  if (!ok) {
+    console.error(pc.red('\nMissing prerequisites. Install the required tools and try again.'));
+    process.exit(1);
+  }
+}

package/src/s3.js

@@ -0,0 +1,35 @@
+import { S3Client, GetObjectCommand } from '@aws-sdk/client-s3';
+import { createWriteStream, mkdirSync } from 'node:fs';
+import { dirname } from 'node:path';
+import { pipeline } from 'node:stream/promises';
+import pc from 'picocolors';
+
+/**
+ * Downloads docker-compose.yml from an S3 bucket to disk.
+ * Uses the default AWS credential chain — on EC2 this resolves via the instance
+ * profile (IMDSv2). No explicit credentials are required or accepted.
+ *
+ * @param {object} opts
+ * @param {string} opts.bucket
+ * @param {string} opts.key
+ * @param {string} opts.region
+ * @param {string} opts.destPath  Local destination path (e.g. ./fluxup/docker-compose.yml)
+ */
+export async function downloadCompose({ bucket, key, region, destPath }) {
+  const client = new S3Client({ region });
+
+  console.log(pc.dim(`  s3://${bucket}/${key} → ${destPath}`));
+
+  const { Body } = await client.send(
+    new GetObjectCommand({ Bucket: bucket, Key: key })
+  );
+
+  if (!Body) {
+    throw new Error(`Object s3://${bucket}/${key} returned no Body.`);
+  }
+
+  mkdirSync(dirname(destPath), { recursive: true });
+  await pipeline(Body, createWriteStream(destPath));
+
+  console.log(pc.green('✔') + ` docker-compose.yml saved to ${destPath}`);
+}

package/src/secrets.js

@@ -0,0 +1,35 @@
+import {
+  SecretsManagerClient,
+  GetSecretValueCommand,
+} from '@aws-sdk/client-secrets-manager';
+
+/**
+ * Fetches the GHCR token from AWS Secrets Manager at runtime.
+ * Uses the default AWS credential chain — on EC2 this resolves via the instance
+ * profile (IMDSv2). The token is kept in memory only — never written to disk.
+ *
+ * @param {object} opts
+ * @param {string} opts.secretName  Secret name or ARN (e.g. 'fluxup/ghcr-token')
+ * @param {string} opts.region      AWS region
+ * @returns {Promise<string>} GHCR token
+ */
+export async function fetchGhcrToken({ secretName, region }) {
+  const client = new SecretsManagerClient({ region });
+
+  const response = await client.send(
+    new GetSecretValueCommand({ SecretId: secretName })
+  );
+
+  const raw = response.SecretString;
+  if (!raw) {
+    throw new Error(`Secret "${secretName}" has no SecretString.`);
+  }
+
+  // Supports secret as JSON { "token": "ghp_..." } or plain string
+  try {
+    const parsed = JSON.parse(raw);
+    return parsed.token ?? parsed.GHCR_TOKEN ?? raw;
+  } catch {
+    return raw.trim();
+  }
+}

package/src/wizard.js

@@ -0,0 +1,58 @@
+import * as p from '@clack/prompts';
+import pc from 'picocolors';
+import { ENV_SCHEMA } from './env.schema.js';
+
+/**
+ * Collects all environment variables via grouped interactive prompts.
+ * Fields marked with secret:true use masked input.
+ *
+ * @param {Record<string, string>} existing  Pre-existing values (e.g. from --non-interactive env vars)
+ * @returns {Promise<Record<string, string>>}
+ */
+export async function runWizard(existing = {}) {
+  const answers = { ...existing };
+
+  const groups = [...new Set(ENV_SCHEMA.map((e) => e.group))];
+
+  p.intro(pc.bgBlue(pc.white(' FluxUp Install — Configuration ')));
+
+  for (const group of groups) {
+    const fields = ENV_SCHEMA.filter((e) => e.group === group);
+
+    p.log.step(pc.bold(group));
+
+    for (const field of fields) {
+      if (answers[field.key] !== undefined && answers[field.key] !== '') {
+        p.log.info(`${field.key} = ${field.secret ? '***' : answers[field.key]}  (kept)`);
+        continue;
+      }
+
+      const value = field.secret
+        ? await p.password({
+            message: field.prompt,
+            validate(v) {
+              if (!field.default && !v) return 'Required.';
+            },
+          })
+        : await p.text({
+            message: field.prompt,
+            defaultValue: field.default,
+            placeholder: field.default ?? '',
+            validate(v) {
+              if (!field.default && !v) return 'Required.';
+            },
+          });
+
+      if (p.isCancel(value)) {
+        p.cancel('Installation cancelled.');
+        process.exit(0);
+      }
+
+      answers[field.key] = value || field.default || '';
+    }
+  }
+
+  p.log.success('Configuration collected.');
+
+  return answers;
+}