# How to Self-Host AFFiNE: Complete Setup Guide for 2026 > Deploy a self-hosted AFFiNE workspace in 2026. See what the official Docker stack requires and how Kuberns simplifies databases, storage, HTTPS, and logs. - **Author**: vamsi-mullapudi - **Published**: 2026-02-20 - **Modified**: 2026-10-01 - **Category**: Open Source - **URL**: https://kuberns.com/blogs/how-to-self-host-affine/ --- AFFiNE can be self-hosted with its official Docker Compose stack, which runs the application with a migration service, PostgreSQL, Redis, and persistent file storage. A public production instance also needs a correct external URL, HTTPS, WebSocket support, backups, monitoring, and a safe upgrade process. If you want that control without configuring and maintaining the Compose stack yourself, you can deploy a managed self-hosted AFFiNE instance through [Kuberns](https://kuberns.com/). Kuberns is an Agentic AI platform for deployment, and its AFFiNE template prepares the application services and gives you a browser-accessible HTTPS endpoint through a guided workflow. This guide explains what AFFiNE self-hosting requires, how to deploy it on Kuberns, what to verify before inviting users, and how the managed route differs from operating AFFiNE on your own VPS or Kubernetes cluster. ## TL;DR: How to Self-Host AFFiNE - AFFiNE recommends Docker Compose for a manual self-hosted installation. - Its current Compose stack includes the AFFiNE server, a migration service, PostgreSQL with vector support, and Redis. - You must plan persistent storage for the database, uploaded files, and configuration. - A public instance also needs HTTPS, WebSocket support, backups, upgrades, monitoring, and a secured administrator setup. - If you do not want to operate that stack yourself, select the AFFiNE template on Kuberns, enter the project details, deploy it, and verify the workspace. ## What Does AFFiNE Self-Hosting Require? The [official AFFiNE self-hosting page](https://getaffineapp.com/self-host) recommends Docker Compose as the starting point. Docker Compose is not the only possible deployment target, but it defines the application architecture that any alternative must support. ### The AFFiNE Service Stack The current [official AFFiNE Compose configuration](https://github.com/toeverything/AFFiNE/blob/canary/.docker/selfhost/compose.yml) defines four services: | Service | Purpose | |---|---| | AFFiNE server | Serves the web application and application API | | Migration service | Applies database migrations before the application starts | | PostgreSQL | Stores users, workspaces, documents, and application data | | Redis | Supports the application runtime and coordination between services | The PostgreSQL service uses an image with vector support. The AFFiNE server and migration service must use compatible application versions because migrations change the database schema expected by the running server. ### Storage, Networking, and Security A usable production deployment needs more than running containers: - **Persistent database storage:** PostgreSQL data must survive container replacement and server restarts. - **Persistent file storage:** Uploaded files and other AFFiNE storage must be kept outside an ephemeral container layer. - **Configuration storage:** Keep the instance configuration with the deployment and include it in backups. - **Public URL:** Configure the final application URL so generated links and callbacks do not point to localhost. - **HTTPS and WebSockets:** Secure browser features and real-time collaboration depend on a correctly configured public connection. - **Administrator setup:** Restrict access until the initial administrator has been created. - **Backups and recovery:** Back up PostgreSQL, uploaded files, and configuration, then test a restore. - **Controlled upgrades:** Review release notes, back up the instance, and account for migrations before changing versions. AFFiNE also supports teams that want to adapt its images to their own cluster. Kubernetes offers more orchestration control, but it also adds work around storage classes, secrets, networking, health checks, updates, and database operations. The official self-hosting guidance presents Docker Compose as the recommended starting point rather than requiring Kubernetes. If you are still deciding how much infrastructure your team should operate, compare [self-hosted and fully managed hosting](https://kuberns.com/blogs/self-hosted-vs-fully-managed-hosting/) before choosing the deployment route. ## Best Way to Self-Host AFFiNE Without Managing Docker For teams that want a dedicated AFFiNE deployment but do not want to assemble and operate the Docker stack manually, Kuberns provides a managed template workflow. The [Kuberns AFFiNE deployment documentation](https://docs.kuberns.com/docs/templates/affine) describes the components and steps handled by the template. ### Step 1: Open the AFFiNE Template Open the [Kuberns template library](https://kuberns.com/deploy), select the [AFFiNE template](https://kuberns.com/deploy/affine), and begin the deployment flow. ![Select the AFFiNE deployment template on Kuberns](https://kuberns-blogs-media.s3.ap-south-1.amazonaws.com/affine-template-page.png) The template is designed to deploy AFFiNE with the supporting PostgreSQL and Redis services required by the application. This avoids copying a Compose file, connecting services manually, and exposing database credentials in an unmanaged setup. ### Step 2: Sign In to Kuberns Create a Kuberns account or sign in and complete the onboarding flow. Kuberns plans start at $7, a Trial Option is available, and bundle packs can provide additional savings. ![Complete the Kuberns onboarding flow for AFFiNE deployment](https://kuberns-blogs-media.s3.ap-south-1.amazonaws.com/affine-onboarding.png) ### Step 3: Enter the Project Details Give the AFFiNE service a recognizable project name and select the available deployment region that fits your team. ![Enter the AFFiNE project details in Kuberns](https://kuberns-blogs-media.s3.ap-south-1.amazonaws.com/affine-project-details.png) The current Kuberns template documentation states that users do not need to enter the internal database, Redis, or application secrets during this flow. Those values belong to the template configuration rather than the user-facing project form. ### Step 4: Deploy the AFFiNE Stack Start the deployment and follow its progress. According to the Kuberns documentation, the template prepares the AFFiNE service, PostgreSQL, Redis, networking, HTTPS, and health checks. ![Follow the AFFiNE deployment progress in Kuberns](https://kuberns-blogs-media.s3.ap-south-1.amazonaws.com/affine-deployment.png) Do not treat a completed build as the final verification. Wait until the service is running, open the assigned URL, and review the runtime logs for migration or startup errors. ### Step 5: Open and Verify AFFiNE Open the application URL shown in the Kuberns dashboard and complete the initial AFFiNE administrator setup. ![Open the deployed AFFiNE workspace from the Kuberns dashboard](https://kuberns-blogs-media.s3.ap-south-1.amazonaws.com/affine-kuberns-dashboard.png) Before inviting the team, verify that you can: - Sign in through the final HTTPS URL. - Create, edit, and reopen a document. - Upload and retrieve a file. - Create a second test user and confirm collaboration works. - Restart or redeploy the service without losing the test content. - Review the application and migration logs. - Configure the final custom domain before distributing workspace links. ## AFFiNE on Kuberns vs Manual Docker Self-Hosting Both routes can produce a working AFFiNE instance, but they give the operator different levels of control and responsibility. | Area | Manual Docker or VPS | Kuberns template | |---|---|---| | AFFiNE services | Configure and run the Compose stack | Prepared through the template workflow | | PostgreSQL and Redis | Configure, secure, connect, and maintain | Provisioned as part of the documented template | | Persistent storage | Choose paths or volumes and verify persistence | Confirm the storage provided by the deployed service | | HTTPS and public routing | Configure a proxy, DNS, certificates, and WebSockets | HTTPS endpoint is provided through the platform workflow | | Secrets | Create and protect database and application secrets | Internal template configuration is handled by the platform | | Backups and restores | Design, schedule, store, and test them | Confirm the available backup and recovery controls for the selected plan | | Updates and migrations | Review releases, back up, update images, and monitor migrations | Confirm how application updates are scheduled and applied by the platform | | Logs and health | Configure log access and monitoring | Review build, migration, and runtime information in the platform | | Infrastructure control | Highest control and customization | Lower operational workload with less direct infrastructure control | Manual deployment is appropriate when your team wants root access, custom networking, an existing Kubernetes environment, or direct control over every component. Kuberns is the more direct route when the goal is to run AFFiNE without first becoming the operator of its database, cache, container, proxy, and certificate stack. Database operations can become a major part of running AFFiNE manually. This comparison of [managed PostgreSQL hosting](https://kuberns.com/blogs/best-managed-postgresql-hosting/) explains which database responsibilities a managed service can remove. ## AFFiNE Self-Hosting Limitations and Operating Considerations Self-hosting changes who is responsible for the workspace. It does not remove the need for infrastructure, storage, security, and lifecycle management. - **Capacity still matters:** Available CPU, memory, and storage determine how many users and files the instance can handle reliably. - **Uploads drive storage growth:** Plan storage based on file uploads as well as the PostgreSQL database. - **Backups need multiple components:** A database dump alone does not include uploaded files or instance configuration. - **Upgrades can run migrations:** Back up first and keep the application and migration service on compatible versions. - **Real-time collaboration needs WebSockets:** A proxy that does not pass WebSocket upgrades can load the interface while breaking synchronization. - **AI may require separate configuration:** Do not assume a self-hosted instance includes a hosted AI subscription. Check the current AFFiNE version and bring-your-own-provider requirements. - **Feature and collaboration limits can change:** Verify the current AFFiNE license, edition, and feature documentation instead of assuming unlimited seats or permanent access to every cloud feature. - **Managed hosting changes the control boundary:** Kuberns reduces setup and runtime administration, while manual Docker or Kubernetes gives your team more direct infrastructure control. The page should not promise unlimited members, flat costs regardless of team size, or unlimited storage. Those outcomes depend on the AFFiNE edition, hosting plan, and resources assigned to the instance. ## Conclusion The official way to self-host AFFiNE is to run its Docker Compose stack and operate the application, migration service, PostgreSQL, Redis, persistent storage, HTTPS, backups, and upgrades yourself. That route offers the most infrastructure control, but it also makes your team responsible for the entire production lifecycle. If your goal is to use AFFiNE without maintaining that stack manually, the [AFFiNE template on Kuberns](https://kuberns.com/deploy/affine) provides the more direct route. Select the template, enter the project details, deploy the services, and verify the administrator account, persistence, collaboration, logs, and final domain before inviting users. Deploy a managed self-hosted AFFiNE workspace with Kuberns ## Frequently Asked Questions About Self-Hosting AFFiNE ### What is the easiest way to self-host AFFiNE? The official self-hosting route is Docker Compose. If you do not want to configure and maintain the application, PostgreSQL, Redis, persistent storage, HTTPS, and updates yourself, the AFFiNE template on Kuberns provides a managed deployment workflow. ### What services are required to self-host AFFiNE? The official AFFiNE Compose stack includes the AFFiNE application, a one-time migration service, PostgreSQL with vector support, and Redis. A production deployment also needs persistent storage, a public URL, HTTPS, WebSocket support, backups, and an upgrade process. ### Can AFFiNE run on Kubernetes? Yes. AFFiNE can be adapted to a Kubernetes or other orchestration environment, but Docker Compose is the recommended starting point in AFFiNE's self-hosting guidance. Kuberns is an alternative for teams that do not want to configure or operate a Kubernetes cluster. ### What are the limitations of self-hosted AFFiNE? Self-hosting gives you control but makes your team responsible for compute capacity, persistent storage, backups, recovery, security updates, and version upgrades. Features such as AI may also need separate provider configuration or credentials. ### Does self-hosted AFFiNE include AI features? Do not assume that an AFFiNE self-hosted deployment includes a hosted AI subscription. AI availability depends on the AFFiNE version and configuration and may require bring-your-own-provider credentials. Check the current AFFiNE documentation before enabling it. ### How do I back up a self-hosted AFFiNE instance? Back up the PostgreSQL database, uploaded-file storage, and AFFiNE configuration. Store the backups away from the running server and test a restore before relying on the backup process. ### How is AFFiNE Cloud different from self-hosting? AFFiNE Cloud is operated by AFFiNE. Manual self-hosting runs the stack on infrastructure you administer. A managed deployment through Kuberns gives you a dedicated AFFiNE deployment workflow while Kuberns handles the platform setup and runtime operations described in its deployment documentation. ### Do I need Docker or Kubernetes to deploy AFFiNE on Kuberns? No. The Kuberns AFFiNE template is intended for users who do not want to write a Docker Compose file or operate a Kubernetes cluster. You select the template, enter the project details, deploy it, and verify the resulting workspace. --- - [More Open Source articles](https://kuberns.com/blogs/category/open-source/1/) - [All articles](https://kuberns.com/blogs/)