Why Self-Host Duckie?
Teams usually self-host Duckie for one or more of these reasons:- Data residency: keep application data, knowledge content, run history, and embeddings in infrastructure you control.
- Security and compliance: align Duckie with your internal network, secrets, audit, and access-control requirements.
- Private integrations: connect Duckie to internal systems, APIs, and tools that are not available from the public internet.
- Upgrade control: decide when new Duckie versions are promoted through development, staging, and production.
- Operational ownership: run Duckie with your existing monitoring, backup, incident response, and change-management processes.
Self-Hosting Options
Duckie supports three self-hosting models.| Option | Best for | How it runs |
|---|---|---|
| Docker Compose | Proofs of concept, internal deployments, and smaller production environments | Runs Duckie services on a Linux server or VM using Compose profiles |
| Kubernetes | Teams already operating EKS, GKE, AKS, or a self-managed cluster | Runs Duckie services as Kubernetes workloads with standard secrets, ingress, scaling, and policy controls |
| AWS Terraform | AWS teams that want infrastructure managed as code | Provisions an AWS environment for Duckie using ECS Fargate, an Application Load Balancer, ElastiCache Redis, Secrets Manager, CloudWatch, and related AWS resources |
Docker Compose
Docker Compose is the simplest way to run Duckie yourself. It is a good fit when you want a single-server deployment, an internal proof of concept, or a lower-ops production setup. Compose profiles let you choose which service groups to run. You can run only the core services, add ingestion and analytics workers, or enable optional integration services when you need them. Use Docker Compose when:- You want the fastest path to a working self-hosted environment.
- Your traffic volume does not require a full orchestration platform.
- Your team is comfortable managing a Linux host or VM directly.
Kubernetes
Kubernetes is the best fit when your team already uses Kubernetes for production workloads. Duckie services run as Kubernetes workloads, with ingress for the web application and internal service-to-service traffic inside the cluster. The Kubernetes setup supports common production patterns such as secrets management, ingress, horizontal scaling, resource isolation, and network policy. It also works with standard GitOps workflows where image tags and manifests are promoted through environments. Use Kubernetes when:- Your platform team already manages EKS, GKE, AKS, or a self-managed cluster.
- You want Kubernetes-native scaling, rollout, and policy controls.
- You want to manage Duckie alongside other internal services.
AWS Terraform
The AWS Terraform option is built for teams that want Duckie infrastructure provisioned as code on AWS. It uses ECS Fargate for application services and provisions supporting AWS resources such as an Application Load Balancer, ElastiCache Redis, Secrets Manager, CloudWatch, and GuardDuty. This option is useful when your team wants an AWS-native deployment without managing Kubernetes nodes or cluster operations. Use AWS Terraform when:- AWS is your standard production platform.
- You want infrastructure, service sizing, secrets wiring, and environments represented in Terraform.
- You want ECS-based deployments with AWS-native monitoring and security services.
How Self-Hosting Works
All self-hosted options run the same Duckie application services. The deployment model changes how those services are packaged, scaled, and operated. At a high level:- Web app serves the Duckie dashboard, API routes, webhooks, and browser-facing application.
- Agent execution services run agent workflows, LLM orchestration, tool calls, assistant flows, and autonomous agent work.
- Integration runtime and tool services coordinate external tools and connected systems.
- Background workers handle knowledge ingestion, web scraping, analytics, launchpad, billing jobs, alerts, and other asynchronous work when those features are enabled.
- Redis handles queues and cache for service coordination.
- Qdrant stores vector embeddings for semantic search and knowledge retrieval.
- Supabase/Postgres stores application data. You can use a managed Supabase project or run Supabase in your own environment.
What You Operate
Self-hosting gives your team control over the runtime environment. It also means your team owns the infrastructure operations around that environment.| Area | What it means |
|---|---|
| Network | Decide which endpoint is public, how TLS is terminated, and which internal services can talk to each other. |
| Database | Operate or configure the Supabase/Postgres environment, including backups, migration windows, and access controls. |
| Vector store | Operate or configure Qdrant for knowledge retrieval. |
| Secrets | Store API keys, OAuth credentials, database credentials, and internal tokens in your secrets system. |
| Observability | Monitor service health, queues, logs, and infrastructure using your preferred tooling. |
| Scaling | Size and scale web, agent, worker, Redis, and Qdrant capacity based on your traffic and feature usage. |
Data and Secrets
In a self-hosted deployment, application data is stored in the database and vector store that you operate or configure for the environment. Secrets such as provider API keys, OAuth credentials, database credentials, and internal service tokens are supplied through your deployment platform:- Environment variables for Docker Compose
- Kubernetes Secrets or your Kubernetes secrets operator
- AWS Secrets Manager for the AWS Terraform option
Database Options
Duckie uses Supabase/Postgres as its database layer. You can choose the option that matches your residency and operations requirements:| Option | When to use it |
|---|---|
| Managed Supabase | You want Supabase to operate the database while Duckie services run in your infrastructure. |
| Self-hosted Supabase | You need the database layer to run fully inside your environment. Docker and Kubernetes setups include self-hosted Supabase paths. |
Choosing an Option
Choose Docker Compose if you want the simplest operational model and do not need a full orchestration platform. It is the most direct option, but scaling and failover are more manual. Choose Kubernetes if your team already standardizes on Kubernetes for production services, GitOps, ingress, secrets, autoscaling, and network policy. It gives you the most platform flexibility if Kubernetes is already part of your operating model. Choose AWS Terraform if you want Duckie infrastructure provisioned in AWS with Terraform and deployed onto ECS Fargate. It is the most AWS-native option and avoids Kubernetes operations.| Question | Usually points to |
|---|---|
| Do you need the fastest self-hosted proof of concept? | Docker Compose |
| Do you already run production services on Kubernetes? | Kubernetes |
| Do you want AWS infrastructure created and managed with Terraform? | AWS Terraform |
| Do you need GitOps-style environment promotion? | Kubernetes or AWS Terraform |
| Do you need the lowest operational surface area? | Docker Compose or AWS Terraform |
Handling Updates
Self-hosted updates are controlled by your team. Duckie releases updated application containers, and you choose when to roll them out. Typical update flow:- Review the release and any required database changes.
- Deploy the new container images through your chosen platform.
- Apply any required database migrations.
- Verify the web app, background services, integrations, and agent runs.
| Option | Update approach |
|---|---|
| Docker Compose | Pull or build the new images, recreate the services, and apply any required database migrations during your maintenance window. |
| Kubernetes | Update image tags in your Kubernetes configuration or GitOps repo, apply the change, and let Kubernetes roll the workloads. |
| AWS Terraform | Build and push new images, then deploy them to ECS. The AWS setup also supports CodeBuild-based builds, database migration execution when configured, and ECS service updates. |
Update Controls
Self-hosting lets you decide how conservative your update process should be.- Scheduled updates: apply Duckie releases during planned maintenance windows.
- Environment promotion: test a release in development or staging before production.
- Image pinning: deploy explicit image tags instead of relying on floating tags.
- Database review: review required migrations before applying a release.
- Rollback planning: keep the previous image tag and database backup strategy available before production changes.
Preparing for Self-Hosting
Before a self-hosted deployment, align on these decisions with your Duckie team:- Which deployment model you want to use
- Whether Supabase/Postgres is managed or self-hosted
- Where Qdrant and Redis will run
- Which integrations and LLM providers need credentials
- Which domains, TLS certificates, and ingress rules are required
- Which environments you need, such as development, staging, and production
- How updates, backups, monitoring, and incident response will be handled