Skip to content

Clarify Quick Start scope and consider feature flags via .env for enterprise evaluation #294

Closed

Description

@dgatti0213

Description

The Quick Start Docker Compose deployment is often the entry point for teams evaluating FlowFuse, including for enterprise use.

While it works well for getting started quickly, it’s not always clear where the boundary is between:
• a quick demo
• an evaluation environment
• a production / enterprise deployment

Because of this, users often begin modifying the stack to add things like TLS, email, registries, or authentication. In practice this frequently leads to configuration drift or broken deployments, especially when people rely on AI-generated compose changes.

Suggested improvement

Instead of expanding the Quick Start stack, consider supporting optional features via environment flags along with a documented .env.example.

.env.example

DOMAIN=example.com

ENABLE_EMAIL=false
ENABLE_TLS=false
ENABLE_PRIVATE_NPM=false
ENABLE_TEAM_BROKER=true
ENABLE_FILE_STORAGE=true

POC option

POC_DNS=true

This would keep Quick Start simple while giving enterprise evaluators a clear and supported path to enable additional features without modifying the compose file.

Activity

  1. ppawlowski commented on Mar 10, 2026

    @ppawlowski
    Contributor
    1. This is not possible - Docker Compose configuration file is a simple yaml where conditional logic cannot be applied
    2. As explained in the docs, the quick start Docker Compose YAML file (docker-compose-quick-start.yml) is used for evaluation purposes only.
    3. As mentioned in the docs, full deployment is available using the docker-compose.yml file. Full guide available here.
  2. dgatti0213 commented on Mar 10, 2026

    @dgatti0213
    Author

    So the ask is not really “add conditional YAML to Quick Start,” but rather make it clearer which features are intentionally disabled in Quick Start and how enterprise evaluators are expected to enable them.

    Right now, several capabilities that are fairly typical in enterprise deployments are either missing or only partially represented in the evaluation path, for example:
    • private npm registry for managing Node-RED dependencies
    • TLS / certificate management
    • email / SMTP configuration
    • identity / auth integrations
    • broker exposure patterns for multi-site deployments
    • storage configuration beyond the default local setup

    When teams evaluate FlowFuse for enterprise use, they typically start with Quick Start and then begin adding these capabilities themselves. In practice this often leads to configuration drift or broken deployments, especially when people rely on partial documentation or AI-generated Compose changes.

    The core issue I’m trying to highlight is not Docker Compose syntax, but the lack of a clear, supported feature-enablement path between Quick Start and a fuller deployment suitable for enterprise evaluation.

  3. hardillb commented on Mar 10, 2026

    @hardillb
    Contributor

    We should probably just remove the Quick Start option, the normal deployment will come up with just a domain adding to the .env file.

    The fact it starts a bunch of extra unused containers is worth it to save on the problems of retro actively trying to enable them.

  4. dgatti0213 commented on Mar 10, 2026

    @dgatti0213
    Author

    I 100% agree! This way, when someone comes to me with some random YAML file, I can compare it to one golden source of truth. I currently get these weird middle grounds...

  5. MichaelBDavis commented on Mar 18, 2026

    @MichaelBDavis

    @Yndira-E Please update the the quick start guide, https://flowfuse.com/docs/quick-start/, by removing the existing code blocks and replacing with how to set up an environment file for the full docker compose.

    Change Step 2: docker-compose-quick-start.yml to docker-compose.yml
    Add a section for setting up an environment file

    This affected these two customers last week:
    https://app-eu1.hubspot.com/contacts/26586079/record/0-3/252826054853
    https://app-eu1.hubspot.com/contacts/26586079/record/0-3/307978792128

  6. ppawlowski commented on Mar 18, 2026

    @ppawlowski
    Contributor

    This is the engineering part of the documentation. I will take care of it @MichaelBDavis .

  7. added and removed
    needs-triageNeeds looking at to decide what to do
    on Mar 18, 2026
  8. added this to the 2.29 milestone on Mar 18, 2026
  9. dgatti0213 commented on Mar 18, 2026

    @dgatti0213
    Author

    I think there is a disconnect on what is considered engineering docs vs customers docs.

    I can tell you from a customer experience, this is the only section that is perceived as engineering documentation: https://flowfuse.com/docs/contribute/introduction/

    Everything else is Customer focused.

  10. ppawlowski commented on Mar 18, 2026

    @ppawlowski
    Contributor

    customer docs - ok, still, the Docker Compose part of the documentation is a technical one, and I do not expect Yndira to cover it.

  11. Yndira-E commented on Mar 19, 2026

    @Yndira-E
    Contributor

    I agree that the technical aspects sit within engineering.

    Since we’re moving to a single installation path, I had a look at the Docker install page; a couple of UX improvements could make it clearer and set expectations earlier:

    Intro

    We could make the intent of the guide clearer by adding something along the lines of "It is suitable for evaluation and production deployments."

    Adding an estimate of setup time could also help users understand what they’re getting into (if feasible).

    Checklist clarity

    The checklist uses icons + tooltips (“required for operation” / “recommended for production”), but without hovering this isn’t obvious.

    Making this explicit (e.g. grouping into Required and Recommended) would reduce ambiguity and work better across devices.

  12. modified the milestones: 2.29, 2.30 on Mar 20, 2026
  13. modified the milestones: 2.30, 2.29 on Mar 27, 2026
  14. moved this from Todo to Review in 🛠 Developmenton Mar 27, 2026
  15. self-assigned this
    on Mar 27, 2026
  16. ppawlowski commented on Apr 9, 2026

    @ppawlowski
    Contributor

    Documentation has been adjusted, and the quick-start Docker Compose file has been removed from the repository. Closing as completed.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Labels

Type

No type

Projects

Milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions