Skip to content

Production Setup

Jump to bottom
Nighty edited this page Dec 1, 2025 · 6 revisions

Deploying Production

Setting Philomena up for production deployment is a bit more involved and will require some amount of manual work to do. Do not run the development environment in production. It's insecure and not designed to be operated continuously.

In production, Philomena runs in Kubernetes (also known as k8s). We are well aware of the sentiment of "Kubernetes is difficult/bad/overkill," but bear with us. Based on our experience from Philomena instances in production (such as Derpibooru, Furbooru, and Tantabus), and the challenges faced deploying and updating these sites, we determined a more standardized, declarative, and "off the shelf" solution would be the best way to deploy Philomena.

We provide a Helm chart repository with everything you need to deploy Philomena to your Kubernetes cluster. This means everything you have to do in order to get Philomena up and running is to fill out some YAML files, and then run a couple of commands.

Before deploying, consider the following:

  • What is your budget?
  • What volume of posts and visits are you expecting?
  • Do you intend to run Philomena long-term (for longer than 1 year)?

The answers to these questions will help inform your choice of deployment below.

Docker Deployment (Not Recommended)

Choose this option if...

  • You are on a tight budget
  • You don't intend to run Philomena long-term
  • You intend to play around with Philomena with minimal commitment
  • You expect a small amount of users and content
    • "Small" in this context refers to less than roughly 10,000 images, or 100 active users

Overview:

In this configuration, everything runs on the same machine. You can optionally configure it to use a proper domain name, as opposed to a local domain.

Warning

In case you ever desire to upgrade from this deployment method to our "Recommended Setup", you will have to create a database dump, and bootstrap the new database in the Kubernetes cluster using it. This operation will also require you to recreate all search indices and reindex the site (which can be slow depending on the amount of content you host).

Additionally, this option leaves very little room for growth. If your site "outgrows" your server hardware, you may need to re-deploy everything from scratch, as opposed to seamless migration enabled in the "Recommended Setup".

Prerequisites:

  • One server
    • At least 4 CPU cores
    • At least 16 GB RAM
    • At least 40 GB storage
      • Adjust this number based on the amount of content you wish to host
      • SSD is preferable to HDD, HDD is preferable to remote block storage
      • If you receive a high level of image traffic, HDD/block storage might become oversubscribed with requests

Notes:

  • In general, a "bigger" server is better
  • For minimal deployment, RAM is more important than CPU cores

Find more detailed instructions about the Docker-based deployment here:

https://github.com/philomena-dev/philomena-docker

Kubernetes Deployment (Recommended)

Choose this option if...

  • You intend to host a long-term / permanent Philomena instance
  • You require the best possible security
  • You expect a large amount of content and users
    • Make sure to scale your server hardware in accordance with your expectations

Overview

In this configuration, three servers are used:

  • App server (runs Philomena, OpenSearch, PostgreSQL, Valkey)
  • Web server (runs Caddy, Nginx, and serves as web ingress)
  • Proxy server (runs Go-Camo, Tinyproxy, and serves as web egress)

Prerequisites:

  • The app server
    • At least 4 CPU cores
    • At least 8 GB RAM
      • 16 GB recommended for OpenSearch to function properly
    • At least 40 GB SSD
      • A cloud object storage provider is used to host image data in this deployment strategy (see below)
      • This is sized to hold database and search engine contents
  • The web server
    • At least 2 CPU cores
    • At least 2 GB of RAM
      • 4 GB or more recommended for improving cache hit rates
    • At least 20 GB SSD
      • Can be sized down, but cache hit rates may decrease
  • The proxy server
    • At least 2 CPU cores
    • At least 2 GB of RAM
  • A website domain and separate image CDN domain
  • An object storage bucket for images (we recommend Cloudflare R2)
  • (optional) Cloudflare or similar service, with the website domain proxied
    • DDoS protection will help keep your site operational against common denial-of-service vectors
    • Anti-bot features provide some protection against abusive crawlers
  • (optional) An object storage bucket for redundant image storage (we recommend Backblaze B2]
  • (optional) An object storage bucket for database backups (Backblaze B2 recommended)

Availability considerations:

  • A separate image CDN domain is used to protect the website domain from being globally blocked if malicious files are uploaded or proxied through Go-Camo (this is a hazard inherent to the widely-used Google Safe Browsing list)
    • If this is not important to your threat model, the CDN domain could instead be organized as a subdomain of the website domain to save cost
  • Each server should ideally live on a distinct ISP, to minimize fate-sharing in the event the servers are targeted by network-level attacks

TODO: write the actual guide

Clone this wiki locally