ddev-floci-ui

A DDEV add-on that runs Floci UI — the local cloud console — against whichever Floci emulators your project has installed.

One console per project, showing AWS, Azure and GCP side by side.

• Installation
• Working on this add-on locally
• Why it is a separate add-on
• How it finds your emulators
• Versus the “Open Floci UI” button
• The ddev floci-ui command
• Configuration
• Removing the add-on
• Licensing
• Credits

Installation

You usually do not install this directly. Each emulator add-on declares it as a dependency, so DDEV pulls it in:

ddev add-on get codementality/ddev-floci-aws   # or -gcp, or -az
ddev restart
ddev floci-ui

Installing it on its own works too, and is worth doing if you want the console before you have picked a cloud:

ddev add-on get codementality/ddev-floci-ui

Working on this add-on locally

One trap worth knowing if you hack on this repo. Installing an emulator add-on replaces a locally-installed floci-ui with the published release:

ddev add-on get ~/dev/ddev-floci-ui        # your working tree
ddev add-on get codementality/ddev-floci-gcp
# ^ its dependency just overwrote your working tree with the last tagged release

DDEV matches the dependency string codementality/ddev-floci-ui against installed manifest names, and an add-on installed from a local directory registers as plain floci-ui. The names do not match, so DDEV concludes the dependency is missing and installs it from GitHub — silently reverting your changes.

Reinstall from your working tree afterwards:

ddev add-on get ~/dev/ddev-floci-ui

The test suite does exactly this, for exactly this reason.

Why it is a separate add-on

The console is multi-cloud: it takes one endpoint per cloud and shows whichever are reachable. So there should be exactly one per project, no matter how many emulators you install.

Shipping it inside each emulator add-on would break that. Install two of them and you would have two compose files both defining a service named floci-ui — Compose merges them into one incoherent service, and removing either add-on takes the shared console with it. A separate add-on has one definition and one owner.

DDEV handles the bookkeeping. Because each emulator declares dependencies: [codementality/ddev-floci-ui], DDEV installs it automatically, and refuses to remove it while any emulator still needs it:

$ ddev add-on remove floci-ui
Unable to remove add-on: cannot remove add-on 'floci-ui' because the
following add-ons depend on it: floci-gcp

Remove the last emulator and DDEV tells you the console is now orphaned rather than deleting it out from under you.

How it finds your emulators

By container name — ddev-<project>-floci-aws, -floci-az, -floci-gcp — not by the service hostnames floci-aws, floci-az, floci-gcp.

That distinction is load-bearing, and it is worth understanding if you run several projects. This service has to sit on DDEV’s shared ddev_default network so ddev-router can reach it. Every project’s emulator is also aliased by its bare service hostname on that same shared network. So a project with no AWS emulator, asking for floci-aws, resolves to some other project’s AWS emulator — and the console would happily display another project’s buckets and queues. Container names are unique per project, so they cannot collide that way.

The upshot: a cloud you have not installed shows as unavailable, which is the truth.

ddev floci-ui clouds
# aws    unavailable   http://ddev-myproject-floci-aws:4566
# azure  reachable     http://ddev-myproject-floci-az:4577
# gcp    reachable     http://ddev-myproject-floci-gcp:4588

All three endpoints are set whether or not the emulators exist, so installing another one later needs no change here — just ddev restart.

Versus the “Open Floci UI” button

The AWS emulator serves a landing page with an Open Floci UI button, which starts a console of its own. That one is not this one, and it is worth knowing the difference:

So prefer ddev floci-ui. The button still works, and this add-on deliberately stays off port 4500 so the two do not fight — but the button’s console is shared across every project on your machine.

The GCP and Azure emulators have no such landing page or button at all: upstream floci-gcp and floci-az ship no UI controller, so / on those returns Resource not found. This add-on is how those two get a console.

Measured against floci/floci-ui:0.3.0, floci/floci:1.7.0, floci/floci-gcp:0.7.0 and floci/floci-az:0.11.0 on 2026-08-26. Floci is under active development, so this may already be out of date — in particular, a landing page may appear in floci-gcp or floci-az.

The ddev floci-ui command

Configuration

ddev dotenv set .ddev/.env.floci-ui --floci-ui-https-port=4611
ddev restart

Ports 4510/4511 rather than the console’s native 4500, because the button’s global container publishes 0.0.0.0:4500 and a router entrypoint there would lose the race to it.

The router routes by hostname, so these ports are shared cleanly between every project running this add-on — any number can be up at once.

Removing the add-on

ddev add-on remove floci-ui

DDEV refuses while any emulator add-on still declares it as a dependency; remove those first, or keep the console. .ddev/.env.floci-ui is left in place so your settings survive a reinstall.

Licensing

Two different licences are in play here, and it is worth being explicit about which covers what:

• This add-on — the compose files, the ddev floci-ui command, the init scripts and the documentation — is licensed Apache 2.0, matching the DDEV add-on template and DDEV’s own add-ons. See LICENSE.
• Floci UI itself is licensed MIT by the floci-io project, and is entirely separate work.

No Floci source is vendored in this repository. The add-on only references the published floci/floci-ui image, which Docker pulls at runtime; nothing here redistributes Floci code or binaries. If you redistribute this add-on you are redistributing Apache-2.0 material only.

Credits

Floci UI is by the floci-io project, MIT licensed. This add-on packages it under Apache 2.0; see Licensing above.

Behavioural notes in this README were verified against floci/floci-ui:0.3.0 on 2026-08-26. Upstream ships frequently; the nightly workflow in .github/workflows/tests.yml re-runs the suite against latest every day, which is what catches drift.

Contributed and maintained by @codementality