Installation Guide

Step-by-step deployment instructions for every supported platform — Windows, Linux, Docker, and Kubernetes. Gets FlowSquad running; the Setup Guide covers first-run configuration.

1. Overview & Prerequisites

FlowSquad ships as a fully compiled, self-contained binary for each supported platform. No Python interpreter, virtual environment, or dependency installation is required on the target host. All installers are available for download from the official release page:

System Requirements

License File

FlowSquad ships with a bundled evaluation license that activates automatically on first run — no license file is needed to get started. The evaluation license allows 1 product for 30 days with full feature access.

To use multiple products or for production deployments, an enterprise license is required. Contact support@flowsquad.ai to obtain one. Enterprise licenses are applied through Admin Panel → License Management after installation.

2. Installation Options

FlowSquad provides five ready-to-deploy installer packages. Select the package that matches your target platform and deployment model.

3. Windows Portable

The portable package is a self-contained ZIP archive. It requires no installation, runs directly from any folder, and needs no administrator privileges. All application data is written to the user's profile, not the extraction folder.

Prerequisites

• Windows 10 or Windows 11 (64-bit)
• No administrator privileges required
• ~500 MB free disk space for the package; additional space for data
• Port 5000 available (or configure a different port in the Setup Wizard)

Installation Steps

1. Go to https://github.com/flowsquad-ai/Flowsquad/releases/ and download FlowSquad-v2.0-portable.zip.
2. Verify the download integrity by comparing the SHA-256 hash published on the release page:

   Get-FileHash .\FlowSquad-v2.0-portable.zip -Algorithm SHA256

3. Extract the archive to your chosen location — for example, C:\FlowSquad. Avoid extracting to a path that contains spaces.
4. Start FlowSquad using one of the included launcher scripts at the root of the extracted folder:
   • Double-click Start-FlowSquad.bat — simplest option; works from Windows Explorer.
   • Double-click Start-FlowSquad.cmd — shows coloured status output in the console.
   The launcher starts the server in the background, waits up to 60 seconds for it to become ready, then opens http://localhost:5000 in your default browser automatically.
5. Your default browser opens automatically at http://localhost:5000. If it does not open within 60 seconds, navigate there manually.
6. Complete the Setup Wizard to configure your database, admin account, and license.

File and Data Locations

Stopping FlowSquad

Use one of the included stop scripts at the root of the extraction folder:

• Double-click Stop-FlowSquad.bat — stops the running server from Windows Explorer.
• Double-click Stop-FlowSquad.cmd — shows status and confirmation.

Alternatively, right-click the FlowSquad system tray icon and choose Exit.

4. Windows Installer (EXE)

The Windows installer is the recommended method for enterprise Windows deployments. It installs FlowSquad as a proper Windows application with Start Menu and desktop shortcuts, and registers an uninstaller via Programs and Features.

Prerequisites

• Windows 10, Windows 11, or Windows Server 2016 or later (64-bit)
• Administrator privileges required for installation
• ~1 GB free disk space
• Port 5000 (or 443 if using direct HTTPS) available, or configure a different port during setup

Installation Steps

1. Go to https://github.com/flowsquad-ai/Flowsquad/releases/ and download FlowSquad-Setup-v2.0.exe.
2. Verify the download:

   Get-FileHash .\FlowSquad-Setup-v2.0.exe -Algorithm SHA256

   Compare the output against the SHA-256 value listed on the release page.
3. Right-click FlowSquad-Setup-v2.0.exe and select Run as administrator.
4. Accept the End User License Agreement.
5. Choose the installation directory. The default is C:\Program Files\FlowSquad.
6. Click Install and wait for completion (approximately 1–2 minutes). The installer creates a desktop shortcut and configures the Windows Firewall automatically — no manual steps are required.
7. On the Finish page, tick "Launch FlowSquad" to start the server and open the browser.
8. Complete the Setup Wizard to configure your database, admin account, and license.

Starting and Stopping FlowSquad

Use the batch scripts installed with FlowSquad:

• Start: double-click Start-FlowSquad.bat in the install folder, or use the FlowSquad Start Menu / desktop shortcut.
• Stop: double-click Stop-FlowSquad.bat in the install folder, or use Stop FlowSquad from the Start Menu, or use Task Manager to end FlowSquad.exe.

What the Installer Creates

• Application files in C:\Program Files\FlowSquad\
• Start-FlowSquad.bat — launch script (handles UAC, readiness polling, browser open)
• Stop-FlowSquad.bat — graceful stop script
• Start Menu entries: FlowSquad, Stop FlowSquad, Documentation, Setup Guide
• Desktop shortcut
• Windows Firewall inbound rule for TCP port 5000
• Uninstaller registered in Programs and Features

File and Data Locations

Uninstalling

Open Control Panel → Programs → Programs and Features, select FlowSquad, and click Uninstall. The uninstaller removes application binaries, the firewall rule, and all shortcuts. Application data stored in %LOCALAPPDATA%\FlowSquad\ is preserved — back up and remove this folder manually if you want a complete removal.

5. Linux Installers

Two Linux packages are available. Both contain the same FlowSquad binary and behave identically at runtime — they differ only in how the service is started and managed.

Option A — Standalone (No systemd)

Use this for a quick start, testing, or environments without systemd.

Prerequisites

• Ubuntu 20.04+ / RHEL 8+ / Debian 11+ (64-bit)
• No root access required (extraction to a user-writable directory is sufficient)
• ~1 GB free disk space

Install and Run

# Download
wget https://github.com/flowsquad-ai/Flowsquad/releases/download/v2.0/FlowSquad-Linux-Standalone-v2.0.tar.gz

# Verify integrity
sha256sum FlowSquad-Linux-Standalone-v2.0.tar.gz

# Extract -- creates FlowSquad-Linux-Standalone-v2.0/ in the current directory
tar -xzf FlowSquad-Linux-Standalone-v2.0.tar.gz
cd FlowSquad-Linux-Standalone-v2.0

# Make scripts executable
chmod +x start-flowsquad.sh stop-flowsquad.sh

# Start (runs in background; prints URL when ready)
./start-flowsquad.sh

# Stop
./stop-flowsquad.sh

FlowSquad is accessible at http://localhost:5000. Open your browser and complete the Setup Wizard.

Option B — Systemd Service (Recommended for Production)

Prerequisites

• Ubuntu 20.04 LTS or later, RHEL / CentOS 8 or later, or Debian 11 or later (64-bit)
• Root or sudo access for initial installation
• Nginx (for HTTPS and production deployments)
• PostgreSQL 14+ or MySQL 8.0+ accessible from the server
• ~1 GB free disk space for the binary; additional space for data

Step 1 — Download and Verify

# Download the Linux Systemd installer from the official release page
wget https://github.com/flowsquad-ai/Flowsquad/releases/download/v2.0/FlowSquad-Linux-Systemd-v2.0.tar.gz

# Verify the download integrity (compare against the hash published on the release page)
sha256sum FlowSquad-Linux-Systemd-v2.0.tar.gz

Step 2 — Extract the Archive

# Extract -- this creates FlowSquad-Linux-Systemd-v2.0/ in the current directory
tar -xzf FlowSquad-Linux-Systemd-v2.0.tar.gz

# Enter the extracted folder
cd FlowSquad-Linux-Systemd-v2.0

Step 3 — Run the Installation Script

The package includes an install.sh script that handles all setup steps automatically (creating the system user, copying files, creating data/log directories, and installing the systemd service).

# Make the installer executable, then run it as root
chmod +x install.sh
sudo ./install.sh

The installer will:

• Create the flowsquad system user
• Copy _internal/ to /opt/flowsquad/
• Create /var/lib/flowsquad/ (data) and /var/log/flowsquad/ (logs)
• Set correct ownership and permissions
• Install flowsquad.service to /etc/systemd/system/ and run systemctl daemon-reload

# Create dedicated system user
sudo useradd --system --no-create-home --shell /usr/sbin/nologin flowsquad

# Create installation directory and copy files
sudo mkdir -p /opt/flowsquad
sudo cp -r _internal /opt/flowsquad/

# Create data and log directories
sudo mkdir -p /var/lib/flowsquad /var/log/flowsquad

# Set ownership and permissions
sudo chown -R root:flowsquad /opt/flowsquad
sudo chmod -R 750 /opt/flowsquad
sudo chmod +x /opt/flowsquad/_internal/flowsquad
sudo chown -R flowsquad:flowsquad /var/lib/flowsquad /var/log/flowsquad

# Install the systemd unit file
sudo cp flowsquad.service /etc/systemd/system/
sudo systemctl daemon-reload

Step 4 — Enable and Start the Service

# Reload systemd to pick up the new unit file
sudo systemctl daemon-reload

# Enable the service to start automatically on boot
sudo systemctl enable flowsquad

# Start the service now
sudo systemctl start flowsquad

# Verify the service is running
sudo systemctl status flowsquad

At this point FlowSquad is running on http://127.0.0.1:5000 (bound to localhost only). Proceed to Section 8 — Deployment Models to configure Nginx and HTTPS.

Viewing Logs

# Follow live logs
sudo journalctl -u flowsquad -f

# Show logs from the last hour
sudo journalctl -u flowsquad --since "1 hour ago"

Service Management Commands

# Stop the service
sudo systemctl stop flowsquad

# Restart the service (e.g., after a configuration change)
sudo systemctl restart flowsquad

# Check service status
sudo systemctl status flowsquad

File and Data Locations

6. Docker Deployment

The Docker package is the recommended deployment method for containerised environments. It ships as a compressed ZIP archive containing a pre-built Docker image, a docker-compose.yml, and ready-to-run deployment scripts — no registry access or internet connection is required at deployment time.

Prerequisites

• Docker Engine 20.10 or later (or Podman — deploy.sh detects either automatically)
• Docker Compose v2.0 or later (or docker-compose v1 / podman-compose as fallback)
• PostgreSQL or MySQL accessible from the Docker host — or let the interactive script start a managed Postgres container for you (see Optional: bundled Postgres below)

Step 1 — Download and Extract

# Download from the official release page
wget https://github.com/flowsquad-ai/Flowsquad/releases/download/v2.0/FlowSquad-Docker-v2.0.zip

# Verify the download
sha256sum FlowSquad-Docker-v2.0.zip

# Extract the archive
unzip FlowSquad-Docker-v2.0.zip
cd FlowSquad-Docker-v2.0

Step 2 — Load the Docker Image

Option A — Using the deployment script (recommended)

# Windows (Command Prompt)
deploy.cmd

# Linux (macOS not officially supported)
chmod +x deploy.sh
./deploy.sh

Both scripts are interactive. They will guide you through each step:

1. System checks — verifies Docker version, Compose, disk space, and memory.
2. Image load — loads the bundled .tar image automatically.
3. Database setup — choose to start a managed Postgres container alongside FlowSquad, or configure your own database later in the Setup Wizard.
4. License check — confirms the bundled evaluation license is in place. The evaluation license (1 product, 30 days) is activated automatically — no separate activation step is needed.
5. Start — starts the container and polls /health until ready.

Skip Steps 3 and 4 if you use this option.

Option B — Manual steps

# Load the pre-built image into the local Docker daemon
docker load < flowsquad-protected-2.0.tar

# Verify the image was loaded (image is stored as localhost/flowsquad:2.0)
docker images localhost/flowsquad

Step 3 — Configure docker-compose.yml

The archive includes a docker-compose.yml file pre-configured with sensible defaults. The only values you may need to change are the port mapping and the optional Postgres credentials. No other edits are required before starting.

services:
  flowsquad:
    image: localhost/flowsquad:2.0
    container_name: flowsquad-app
    ports:
      - "5000:5000"        # HTTP — change to 5443:5000 if using HTTPS
    volumes:
      # Persistent FlowSquad data (configuration DB, vector DB, uploaded documents)
      - flowsquad-data:/data

      # LICENSE: Bind the host machine-id into the container for license validation.
      # Linux/macOS hosts: this line is active by default.
      - /etc/machine-id:/etc/host-machine-id:ro
      # Windows hosts: comment out the line above and set FLOWSQUAD_CLUSTER_ID below.

    environment:
      - FLOWSQUAD_DATA_DIR=/data
      # Windows hosts or multi-cluster deployments: set a stable cluster ID
      # - FLOWSQUAD_CLUSTER_ID=your-stable-32-char-hex-id

    restart: unless-stopped
    healthcheck:
      test: ["CMD-SHELL", "curl --fail --silent http://localhost:5000/health || exit 1"]
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 40s

volumes:
  flowsquad-data:
    driver: local

Step 4 — Start the Container

Option A — Using the deployment script (recommended)

Already done — the script in Step 2 starts the container automatically.

Option B — Manual

# Start in the background
docker compose up -d

# Verify the container is healthy
docker compose ps

# Follow startup logs
docker compose logs -f flowsquad

FlowSquad is now accessible at http://localhost:5000 (or the configured host port). Complete the Setup Wizard on first access.

Management Commands

Windows (deploy.cmd) — pass a flag for direct management:

deploy.cmd /Status       # check container status and log level
deploy.cmd /Logs         # follow live logs (Ctrl+C to exit)
deploy.cmd /Stop         # stop the container
deploy.cmd /Help         # show all available options

Linux (deploy.sh) — re-run the script; if FlowSquad is already running it shows a management menu:

./deploy.sh

The menu offers: View logs, Restart, Stop, Re-deploy, and Collect a support bundle.

Non-interactive troubleshooting sub-commands are also available directly:

./deploy.sh selftest      # verify the application binary is intact
./deploy.sh diagnostics   # collect a support bundle (.tar.gz)
./deploy.sh debug         # restart with DEBUG logging
./deploy.sh nodebug       # restart with normal INFO logging

Or use Docker Compose directly:

# Stop all services
docker compose down

# Restart FlowSquad
docker compose restart flowsquad

# Update to a new version (load new image, then restart)
docker load < flowsquad-vX.Y.tar
docker compose up -d

# Back up the persistent data volume
docker run --rm \
  -v flowsquad-data:/data:ro \
  -v $(pwd):/backup \
  alpine tar czf /backup/flowsquad-backup-$(date +%Y%m%d).tar.gz /data

# View real-time logs
docker compose logs -f

Optional: Bundled Postgres Container

For users who do not have an existing PostgreSQL server, the deploy scripts can start a managed Postgres container alongside FlowSquad. Both containers share the same Docker network — no external database or extra networking required.

Linux (deploy.sh) — the interactive script asks about the database during deployment. Select "Start a managed PostgreSQL container" and enter the settings when prompted (version, database name, user, password, port). The script saves these to a .env file and starts both containers.

Windows (deploy.cmd) — pass the /WithPostgres flag and set a password before running:

:: Set password (required — Postgres refuses to start without one)
set POSTGRES_PASSWORD=your-strong-password

:: Deploy FlowSquad + bundled Postgres
deploy.cmd /WithPostgres

Alternatively, create a .env file in the same folder so the password is reused on every deploy:

echo POSTGRES_PASSWORD=your-strong-password > .env
deploy.cmd /WithPostgres

Enter these values in the Setup Wizard → Database step:

The database name and username default to flowsquad. Override them by setting POSTGRES_DB and POSTGRES_USER in your environment or .env file before running the deploy command. Postgres data is persisted in a separate named volume (postgres-data) and survives container restarts and image upgrades.

7. Kubernetes Deployment

Deploy FlowSquad to Kubernetes for high-availability and auto-scaling production environments. The Kubernetes package is a separate download — FlowSquad-Kubernetes-v2.0.zip — available from the releases page. It ships in two flavours:

• Raw manifests — eight numbered YAML files (01-namespace.yaml through 08-hpa.yaml) plus a deploy.sh script that applies them in order.
• Helm chart — a fully parameterised chart in flowsquad-helm-2.0.tgz for teams already using Helm.

Prerequisites

• Kubernetes 1.21 or later with kubectl installed and configured
• Active cluster connection — the deploy.sh script verifies this automatically with kubectl cluster-info
• Docker Engine 20.10+ on the machine used to load and push the image
• A container registry reachable from your cluster nodes
• An ingress controller (nginx-ingress recommended) and cert-manager for TLS
• A PersistentVolume provisioner in the cluster

Step 1 — Download, Verify, and Extract

# Download the Kubernetes package
wget https://github.com/flowsquad-ai/Flowsquad/releases/download/v2.0/FlowSquad-Kubernetes-v2.0.zip

# Verify the download
sha256sum FlowSquad-Kubernetes-v2.0.zip
# Compare against FlowSquad-Kubernetes-v2.0.zip.sha256 from the release page

# Extract
unzip FlowSquad-Kubernetes-v2.0.zip
cd FlowSquad-Kubernetes-v2.0

Step 2 — Push the Image to Your Registry

The Kubernetes package includes flowsquad-protected-2.0.tar. Load it and push it to your internal registry before deploying. The deploy.sh script handles this interactively — or do it manually:

# Load the bundled image
docker load < flowsquad-protected-2.0.tar

# Tag for your internal registry
docker tag flowsquad:latest your-registry.company.com/flowsquad:v2.0

# Push to the registry
docker push your-registry.company.com/flowsquad:v2.0

chmod +x deploy.sh
./deploy.sh

kubectl apply -f .

Step 3 — Create the Namespace

kubectl create namespace flowsquad

Step 4 — Create the License Secret

Each Kubernetes cluster requires a stable cluster ID that was used when generating the FlowSquad license. Generate the ID once and store it securely — it must never change once the license is issued:

# Generate a stable cluster ID (run once; record the output)
python3 -c "import hashlib,uuid; print(hashlib.sha256(str(uuid.uuid4()).encode()).hexdigest()[:32])"

# Apply the cluster ID secret
kubectl apply -f - <<EOF
apiVersion: v1
kind: Secret
metadata:
  name: flowsquad-machine
  namespace: flowsquad
  labels:
    app: flowsquad
    component: license
type: Opaque
stringData:
  FLOWSQUAD_CLUSTER_ID: "REPLACE_WITH_YOUR_STABLE_CLUSTER_ID"
EOF

Step 5 — Create the Application Secret

kubectl apply -f - <<EOF
apiVersion: v1
kind: Secret
metadata:
  name: flowsquad-secrets
  namespace: flowsquad
type: Opaque
stringData:
EOF

Step 6 — Create a PersistentVolumeClaim

kubectl apply -f - <<EOF
apiVersion: v1
kind: PersistentVolumeClaim
metadata:
  name: flowsquad-data
  namespace: flowsquad
spec:
  accessModes:
    - ReadWriteOnce
  resources:
    requests:
      storage: 20Gi
  storageClassName: standard   # Replace with your cluster's storage class
EOF

Step 7 — Deploy FlowSquad

kubectl apply -f - <<EOF
apiVersion: apps/v1
kind: Deployment
metadata:
  name: flowsquad
  namespace: flowsquad
spec:
  replicas: 1
  selector:
    matchLabels:
      app: flowsquad
  template:
    metadata:
      labels:
        app: flowsquad
    spec:
      containers:
        - name: flowsquad
          image: your-registry.company.com/flowsquad:v2.0
          ports:
            - containerPort: 5000
          env:
            - name: FLOWSQUAD_DATA_DIR
              value: /data
            - name: FLOWSQUAD_CLUSTER_ID
              valueFrom:
                secretKeyRef:
                  name: flowsquad-machine
                  key: FLOWSQUAD_CLUSTER_ID
          volumeMounts:
            - name: data
              mountPath: /data
          livenessProbe:
            httpGet:
              path: /health
              port: 5000
            initialDelaySeconds: 40
            periodSeconds: 30
          resources:
            requests:
              memory: "2Gi"
              cpu: "1000m"
            limits:
              memory: "8Gi"
              cpu: "4000m"
      volumes:
        - name: data
          persistentVolumeClaim:
            claimName: flowsquad-data
EOF

Step 8 — Create a Service and Ingress

# Internal ClusterIP service
kubectl apply -f - <<EOF
apiVersion: v1
kind: Service
metadata:
  name: flowsquad-service
  namespace: flowsquad
spec:
  selector:
    app: flowsquad
  ports:
    - protocol: TCP
      port: 80
      targetPort: 5000
  type: ClusterIP
EOF

# Ingress (requires an ingress controller such as nginx-ingress)
kubectl apply -f - <<EOF
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: flowsquad-ingress
  namespace: flowsquad
  annotations:
    nginx.ingress.kubernetes.io/proxy-body-size: "100m"
    nginx.ingress.kubernetes.io/proxy-read-timeout: "300"
    nginx.ingress.kubernetes.io/proxy-send-timeout: "300"
    cert-manager.io/cluster-issuer: "letsencrypt-prod"   # If using cert-manager
spec:
  ingressClassName: nginx
  tls:
    - hosts:
        - flowsquad.company.com
      secretName: flowsquad-tls
  rules:
    - host: flowsquad.company.com
      http:
        paths:
          - path: /
            pathType: Prefix
            backend:
              service:
                name: flowsquad-service
                port:
                  number: 80
EOF

Alternative — Deploy with Helm

If your cluster uses Helm, use the chart included in the Kubernetes package instead of the raw manifests:

# Install using the included chart tarball
helm install flowsquad flowsquad-helm-2.0.tgz \
  --namespace flowsquad --create-namespace \
  --set image.repository=your-registry.company.com/flowsquad \
  --set image.tag=v2.0 \
  --set ingress.hosts[0].host=flowsquad.company.com

# Or customise via a values file (recommended for production)
# Edit flowsquad/values.yaml first, then:
helm install flowsquad flowsquad-helm-2.0.tgz \
  --namespace flowsquad --create-namespace \
  -f my-values.yaml

# Upgrade to a new version
helm upgrade flowsquad flowsquad-helm-NEW.tgz \
  --namespace flowsquad -f my-values.yaml

# Check status
kubectl get all -n flowsquad
helm status flowsquad -n flowsquad

Kubernetes Management Commands

# Check pod and service status
kubectl get all -n flowsquad

# Follow live logs
kubectl logs -n flowsquad -l app=flowsquad -f

# Scale replicas manually
kubectl scale deployment flowsquad -n flowsquad --replicas=5

# Rolling update to a new image
kubectl set image deployment/flowsquad flowsquad=your-registry.company.com/flowsquad:vX.Y -n flowsquad

# Port-forward for local access (dev / testing)
kubectl port-forward -n flowsquad svc/flowsquad-service 5000:80
# Then open: http://localhost:5000

8. Deployment Models (HTTP and HTTPS)

FlowSquad supports two production deployment models. Choose the model that suits your network architecture. Both models are fully supported and enterprise-ready.

Model A — FlowSquad Behind an Nginx Reverse Proxy (Recommended)

In this model FlowSquad runs as a plain HTTP service on 127.0.0.1:5000 (not exposed externally). Nginx handles HTTPS termination, certificate management, and forwards all requests to FlowSquad over the local loopback interface. This is the recommended production architecture because it:

• Simplifies certificate management (certificates live in Nginx, not inside FlowSquad)
• Supports automatic certificate renewal via Let's Encrypt / certbot
• Provides rate limiting, connection limiting, and request buffering at the proxy layer
• Allows zero-downtime FlowSquad restarts without interrupting the TLS session

Step 1 — Install Nginx

# Ubuntu / Debian
sudo apt-get install -y nginx

# RHEL / CentOS / Fedora
sudo dnf install -y nginx
sudo systemctl enable --now nginx

Step 2 — Obtain a Certificate

Use one of the following options:

Option A — Let's Encrypt (public domain, internet-accessible)

# Install certbot
sudo apt-get install -y certbot python3-certbot-nginx   # Ubuntu/Debian
# sudo dnf install -y certbot python3-certbot-nginx     # RHEL/CentOS

# Obtain and install certificate (certbot configures Nginx automatically)
sudo certbot --nginx -d flowsquad.company.com

# Verify automatic renewal
sudo certbot renew --dry-run

Certbot installs a renewal timer at /etc/cron.d/certbot or a systemd timer. Certificates renew automatically 30 days before expiry.

Option B — Enterprise CA or Commercial Certificate

Obtain the following files from your Certificate Authority:

• flowsquad.crt — the certificate for your domain
• flowsquad.key — the private key
• ca-bundle.crt — the intermediate certificate chain (if provided by your CA)

# If a chain file was provided, concatenate it with your certificate
cat flowsquad.crt ca-bundle.crt > /etc/ssl/certs/flowsquad-fullchain.crt

# Or copy the certificate directly (if already a full chain)
sudo cp flowsquad.crt /etc/ssl/certs/flowsquad.crt

# Copy the private key (restrict permissions)
sudo cp flowsquad.key /etc/ssl/private/flowsquad.key
sudo chmod 600 /etc/ssl/private/flowsquad.key
sudo chown root:root /etc/ssl/private/flowsquad.key

Step 3 — Configure Nginx

sudo tee /etc/nginx/sites-available/flowsquad > /dev/null <<'EOF'
upstream flowsquad_backend {
    server 127.0.0.1:5000 max_fails=3 fail_timeout=30s;
    keepalive 32;
}

# Redirect HTTP to HTTPS
server {
    listen 80;
    listen [::]:80;
    server_name flowsquad.company.com;

    # Let's Encrypt renewal challenge
    location /.well-known/acme-challenge/ {
        root /var/www/html;
    }

    location / {
        return 301 https://$server_name$request_uri;
    }
}

# HTTPS — main FlowSquad entry point
server {
    listen 443 ssl http2;
    listen [::]:443 ssl http2;
    server_name flowsquad.company.com;

    # Certificate paths — update to match your certificate location
    ssl_certificate     /etc/ssl/certs/flowsquad.crt;
    ssl_certificate_key /etc/ssl/private/flowsquad.key;

    # TLS security settings (A+ rating)
    ssl_protocols TLSv1.2 TLSv1.3;
    ssl_ciphers 'ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384:ECDHE-ECDSA-CHACHA20-POLY1305:ECDHE-RSA-CHACHA20-POLY1305';
    ssl_prefer_server_ciphers off;
    ssl_session_cache shared:SSL:10m;
    ssl_session_timeout 1d;
    ssl_session_tickets off;

    # OCSP Stapling
    ssl_stapling on;
    ssl_stapling_verify on;
    resolver 8.8.8.8 8.8.4.4 valid=300s;
    resolver_timeout 5s;

    # Security headers
    add_header Strict-Transport-Security "max-age=63072000; includeSubDomains; preload" always;
    add_header X-Frame-Options "SAMEORIGIN" always;
    add_header X-Content-Type-Options "nosniff" always;
    add_header X-XSS-Protection "1; mode=block" always;
    add_header Referrer-Policy "strict-origin-when-cross-origin" always;

    # Logging
    access_log /var/log/nginx/flowsquad-access.log;
    error_log  /var/log/nginx/flowsquad-error.log warn;

    # Allow large file uploads (match your organisation's document size policy)
    client_max_body_size 100M;
    client_body_timeout 300s;
    client_header_timeout 300s;

    # Gzip compression
    gzip on;
    gzip_vary on;
    gzip_proxied any;
    gzip_comp_level 6;
    gzip_types text/plain text/css text/xml text/javascript application/json application/javascript;

    # Proxy to FlowSquad
    location / {
        proxy_pass http://flowsquad_backend;

        # CRITICAL: do NOT let nginx rewrite Location headers from the backend.
        # Without this, nginx rewrites 302 redirects to external Identity Providers
        # (Keycloak, Okta, etc.) during SAML/OAuth2 login, replacing the IdP host
        # with the FlowSquad host. The browser then hits FlowSquad instead of the
        # IdP and gets a 404. See Reference Guide -- nginx for details.
        proxy_redirect off;

        proxy_set_header Host               $host;
        proxy_set_header X-Real-IP          $remote_addr;
        proxy_set_header X-Forwarded-For    $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto  $scheme;
        proxy_set_header X-Forwarded-Host   $server_name;
        proxy_set_header X-Forwarded-Port   $server_port;

        # WebSocket support (required for real-time features)
        proxy_http_version 1.1;
        proxy_set_header Upgrade    $http_upgrade;
        proxy_set_header Connection "upgrade";

        proxy_connect_timeout 300s;
        proxy_send_timeout    300s;
        proxy_read_timeout    300s;

        proxy_request_buffering off;
    }

    # Health check endpoint
    location /health {
        proxy_pass http://flowsquad_backend;
        access_log off;
    }

    # Deny access to hidden files and logs
    location ~ /\. {
        deny all; access_log off; log_not_found off;
    }
}
EOF

# Enable the site
sudo ln -s /etc/nginx/sites-available/flowsquad /etc/nginx/sites-enabled/

# Test Nginx configuration
sudo nginx -t

# Reload Nginx (zero-downtime)
sudo systemctl reload nginx

FlowSquad is now accessible at https://flowsquad.company.com. FlowSquad itself continues to run on plain HTTP internally — Nginx handles all TLS. There is no SSL configuration required inside FlowSquad's Setup Wizard for this model.

Model B — FlowSquad with Direct HTTPS (No Reverse Proxy)

In this model FlowSquad terminates TLS directly. This is suitable for environments where an Nginx reverse proxy cannot be deployed — for example, a standalone Windows server or a Docker container exposed directly to the network. The Setup Wizard configures TLS in this scenario.

Preparing the Certificate Files

Place the following files in a secure directory accessible to FlowSquad (e.g., %LOCALAPPDATA%\FlowSquad\ssl\ on Windows, or /var/lib/flowsquad/ssl/ on Linux):

• flowsquad.crt — the full-chain certificate (certificate + intermediate chain, PEM format)
• flowsquad.key — the private key (PEM format)

On Linux, restrict private key access:

sudo mkdir -p /var/lib/flowsquad/ssl
sudo cp flowsquad.crt /var/lib/flowsquad/ssl/
sudo cp flowsquad.key /var/lib/flowsquad/ssl/
sudo chmod 600 /var/lib/flowsquad/ssl/flowsquad.key
sudo chown flowsquad:flowsquad /var/lib/flowsquad/ssl/flowsquad.key

Configuring HTTPS in the Setup Wizard

1. Open the FlowSquad Setup Wizard (first-run) or navigate to Admin Panel → System Settings → SSL/TLS Configuration.
2. Enable HTTPS.
3. Set Certificate File to the full path of flowsquad.crt.
4. Set Private Key File to the full path of flowsquad.key.
5. Click Test & Save. FlowSquad validates the certificate and private key, then restarts on the HTTPS port.
6. Update your firewall to allow inbound TCP on port 443 and block external access to port 5000.

After configuration, FlowSquad is accessible at https://your-server:443.

9. Environment Variables & Runtime Configuration

FlowSquad reads a set of environment variables at startup. These override the defaults set by the installer and are the correct way to customise the port, bind address, data directory, log level, and cluster ID — without modifying any compiled file or config database.

All Supported Variables

Default Data Directory by Platform

Bind Address: 0.0.0.0 vs 127.0.0.1

By default, FlowSquad binds to 0.0.0.0 (all interfaces), which makes it reachable on any IP address of the host. This is intentional for Docker and Kubernetes, where the container has no external firewall and the port mapping controls external exposure.

How to Change the Bind Address

Linux systemd: add to the [Service] section:

Environment="FLOWSQUAD_HOST=127.0.0.1"

Then reload: sudo systemctl daemon-reload && sudo systemctl restart flowsquad

Docker Compose — add to the environment: block:

environment:
  - FLOWSQUAD_HOST=0.0.0.0   # Keep 0.0.0.0 for Docker; rely on port mapping

Linux Standalone / Windows Portable — set before launching:

# Linux
export FLOWSQUAD_HOST=127.0.0.1
./start-flowsquad.sh

# Windows
set FLOWSQUAD_HOST=127.0.0.1
Start-FlowSquad.bat

Running in Debug Mode

Debug mode enables verbose request/response logging and detailed error pages. Never use DEBUG in production — it logs request payloads, headers, and database queries which may include credentials and user data.

# Linux systemd -- add to [Service] section of the unit file, then reload
Environment="FLOWSQUAD_LOG_LEVEL=DEBUG"
Environment="FLOWSQUAD_ENV=development"

# Linux Standalone
export FLOWSQUAD_LOG_LEVEL=DEBUG
export FLOWSQUAD_ENV=development
./start-flowsquad.sh

# Docker Compose -- add to environment block
- FLOWSQUAD_LOG_LEVEL=DEBUG
- FLOWSQUAD_ENV=development

# Windows (Portable)
set FLOWSQUAD_LOG_LEVEL=DEBUG
set FLOWSQUAD_ENV=development
Start-FlowSquad.bat

Running on a Custom Port

# Linux systemd -- add to [Service] section, then daemon-reload & restart
Environment="FLOWSQUAD_PORT=8080"

# Linux Standalone
export FLOWSQUAD_PORT=8080
./start-flowsquad.sh

# Docker Compose -- change the host-side port mapping AND set the env var
ports:
  - "8080:8080"   # host:container
environment:
  - FLOWSQUAD_PORT=8080

# Windows
set FLOWSQUAD_PORT=8080
Start-FlowSquad.bat

10. Security: TLS & Encryption

TLS / HTTPS

All production deployments must use HTTPS. The recommended approach for Linux and Docker is Nginx as a reverse proxy (Model A in Section 8) — TLS lives in Nginx and FlowSquad runs plain HTTP internally. For Windows or environments without a reverse proxy, configure TLS directly inside FlowSquad (Model B).

Configuration Database Security

The configuration database (flowsquad_engine.db) stores API keys, credentials, and license information. All sensitive values are encrypted at the field level before storage — API keys, passwords, SAML keys, and tokens are never stored in plaintext. Whole-file database encryption is not available; for at-rest protection of the entire database file, use filesystem-level encryption (LUKS/dm-crypt on Linux, BitLocker on Windows, or place the Docker volume on an encrypted filesystem).

File Permissions (Minimum Baseline)

# Linux
chmod 600 /var/lib/flowsquad/flowsquad_engine.db
chown flowsquad:flowsquad /var/lib/flowsquad/flowsquad_engine.db

# Windows (Command Prompt — Administrator)
icacls "%LOCALAPPDATA%\FlowSquad\flowsquad_engine.db" /inheritance:d
icacls "%LOCALAPPDATA%\FlowSquad\flowsquad_engine.db" /remove "Everyone"
icacls "%LOCALAPPDATA%\FlowSquad\flowsquad_engine.db" /grant:r "$env:USERNAME:(R,W)"

Configuration Database — File Locations

11. Post-Install Checklist

Confirm the installation is complete before handing off to the Setup Guide.

• FlowSquad process starts and the browser opens to the Setup Wizard or login page
• HTTPS enabled — either via Nginx reverse proxy (Model A, Section 8) or direct TLS (Model B)
• Certificate is CA-issued (not self-signed) and covers the correct domain name
• Firewall rules verified — port 443 open to users; port 5000 blocked from external access if behind a reverse proxy
• Configuration database file permissions set (chmod 600 on Linux)
• Sensitive credentials verified accessible (API keys, passwords stored encrypted at field level)
• Log rotation configured (see log locations below)
• For Docker: docker compose ps shows container as healthy — or run deploy.cmd /Status / ./deploy.sh status
• For Linux: sudo systemctl status flowsquad shows active (running)
• For Kubernetes: kubectl get all -n flowsquad shows pods Running and service ready

Log File Locations

12. Troubleshooting: Installation & Startup

Windows: Script Won't Run

Batch and CMD files run directly on Windows without any additional configuration. If deploy.cmd or Start-FlowSquad.bat does not start, ensure you are running it from a Command Prompt opened in the same folder as the script, or double-click the file directly in Windows Explorer. Do not move the scripts outside the extraction folder.

Windows / Linux: Port 5000 Blocked by Firewall

If the server starts but the browser cannot reach it, a host firewall is the most likely cause. The deploy and launcher scripts detect this automatically: after a failed health-check they query the firewall, add an inbound allow-rule for TCP 5000, and retry. If automatic fixing fails (e.g. no admin rights), they print the exact manual command. You can also add the rule yourself:

# Windows — run in an elevated (Administrator) Command Prompt:
netsh advfirewall firewall add rule name="FlowSquad-Port-5000" ^
    dir=in action=allow protocol=TCP localport=5000 enable=yes profile=any

# Linux — ufw:
sudo ufw allow 5000/tcp

# Linux — firewalld:
sudo firewall-cmd --add-port=5000/tcp --permanent
sudo firewall-cmd --reload

Cannot Log In with admin / admin After Setup

The default admin / admin account is created during the Setup Wizard → Step 7 (Users), or automatically when you click Complete Setup if no admin was created in Step 7. If login still fails after setup:

1. Check the application log for the line LocalAuthProvider: User 'admin' not found:
   %LOCALAPPDATA%\FlowSquad\logs\flowsquad.log (Windows) or /data/logs/flowsquad.log (Docker)
2. If the line is present, re-open the Setup Wizard as a logged-in global admin and complete Step 7 to create the admin account.
3. If you cannot log in at all, restart FlowSquad — the startup migration will create the account on boot if none exists.

Windows: FlowSquad Won't Start

Symptoms: Running Start-FlowSquad.bat or Start-FlowSquad.cmd shows an error or the browser does not open after 60 seconds.

1. Check whether port 5000 is already in use: Get-NetTCPConnection -LocalPort 5000
2. If another process is using port 5000, use Stop-FlowSquad.bat first to stop any stale FlowSquad instance, or kill the conflicting process: Get-Process -Id (Get-NetTCPConnection -LocalPort 5000).OwningProcess | Stop-Process
3. Review %LOCALAPPDATA%\FlowSquad\logs\flowsquad.log for error details
4. Verify that the _internal\ subfolder exists alongside the start scripts — do not move the scripts outside the extraction folder

Docker: Container Exits Immediately

Symptoms: docker ps -a shows Exited (1).

# Inspect logs
docker logs flowsquad 2>&1 | tail -20

Common causes:

• Volume permission denied (Linux): sudo chown -R 1000:1000 ./data && chmod -R 755 ./data
• Database URL incorrect: verify the service name in docker-compose.yml matches your PostgreSQL service

SSL / TLS Issues

• Browser "Not Secure" warning: Expected for self-signed certificates in dev. For production, obtain a Let's Encrypt or CA-signed certificate.
• Certificate chain incomplete: openssl s_client -connect flowsquad.company.com:443 — verify the full chain is present. Concatenate intermediate CA: cat flowsquad.crt ca-bundle.crt > fullchain.crt
• WebSocket failing: Verify Nginx config includes proxy_http_version 1.1; and the Upgrade and Connection proxy headers (Section 8).
• Certificate expired: Let's Encrypt: sudo certbot renew. Commercial: obtain a new certificate from your CA and update the path in Nginx.

Port Already in Use

# Windows
netstat -ano | findstr :5000
taskkill /PID <pid> /F

# Linux
sudo lsof -i :5000
sudo kill <pid>