Docs: Refactor self-hosted docs (#1223)

Co-authored-by: Christopher Samiullah <[email protected]>

Author: bruno-espino

docs/reference/self-hosted.md

@@ -1,9 +1,15 @@
-# Trying Self Hosted locally
+# Local Quickstart
 
-This guide covers how to setup a local instance, so that you can test, prototype and evaluate Logfire without requiring a full production environment.
+This guide provides a fast path for setting up a local Logfire instance on Kubernetes to test, prototype, and evaluate the product.
+
+For a production setup, including detailed configuration and prerequisites, please refer to our In-Depth [Installation Guide](./installation.md).
+
+---
 
 ## Prerequisites
 
+Before deploying, you will need the following:
+
 - A Logfire Access Key, you'll need to get in contact with [[email protected]](mailto:[email protected]) to get one.
 - A local Kubernetes cluster, we will be using [Kind](https://kind.sigs.k8s.io/) in this example.
 - [Helm](https://helm.sh) CLI installed.
@@ -36,9 +42,11 @@ kubectl create secret docker-registry regcred \
   --docker-email=<YOUR_EMAIL>
 ```
 
-## Installing Logfire
+### Installing Logfire
 
 You can now install Logfire using the Helm chart, with the development dependencies enabled.
+!!! warning
+    These development services are not suitable for production use. They lack persistence, backup, and security configurations.
 
 Here is a minimal command to run Logfire in development mode, you can customize `adminEmail` if you want to access Logfire's self telemetry, but it's not required:
 
@@ -58,39 +66,9 @@ helm install logfire pydantic/logfire \
 ```
 
 You can refer to the [Logfire Helm Chart](https://github.com/pydantic/logfire-helm-chart) documentation to check all the supported configurations.
+Also check our [full installation guide](./installation.md) for a complete checklist and a detailed example `values.yaml` to get you started on your production setup.
 
-
-## Using Logfire
-
-To access your local Logfire installation from you host you'll need to port forward `logfire-service`:
-
-```bash
-kubectl port-forward service/logfire-service 8080:8080
-```
-
-and `logfire-maildev`, for receiving emails and enabling user signups:
-
-```bash
-kubectl port-forward service/logfire-maildev 1080:1080
-```
-
-You are now ready to use Logfire with your browser of choice navigating to `http://localhost:8080/`
-
-You can access the emails for signin up going to `http://localhost:1080`.
-
-After creating your user, your project and your write token, you can start sending data to Logfire in the same fashion as always:
-
-```python
-import logfire
-
-logfire.configure(
-  advanced=logfire.AdvancedOptions(base_url='http://localhost:8080'),
-  token='__YOUR_LOGFIRE_WRITE_TOKEN__'
-)
-logfire.info('Hello, {place}!', place='World')
-```
-
-## Using Tilt
+## Setup with Tilt (Optional)
 
 If you are a [Tilt](https://tilt.dev/) user, you can use this `Tiltfile` to automate the Logfire setup:
 
@@ -157,10 +135,53 @@ LOGFIRE_ADMIN_EMAIL=<ADMIN_EMAIL> \
 tilt up
 ```
 
+## Using Logfire
+
+To access your local Logfire installation from you host you'll need to port forward `logfire-service`:
+
+```bash
+kubectl port-forward service/logfire-service 8080:8080
+```
+
+and `logfire-maildev`, for receiving emails and enabling user signups:
+
+```bash
+kubectl port-forward service/logfire-maildev 1080:1080
+```
+
+You are now ready to use Logfire with your browser of choice navigating to `http://localhost:8080/`
+
+You can access the emails for signin up going to `http://localhost:1080`.
+
+After creating your user, your project and your write token, you can start sending data to Logfire in the same fashion as always:
+
+```python
+import logfire
+
+logfire.configure(
+  advanced=logfire.AdvancedOptions(base_url='http://localhost:8080'),
+  token='__YOUR_LOGFIRE_WRITE_TOKEN__'
+)
+logfire.info('Hello, {place}!', place='World')
+```
+
 ## Cleanup
 
 In order to cleanup your local environment you can just delete the k8s cluster:
 
 ```bash
 kind delete cluster
 ```
+
+## Troubleshooting and support
+
+If you encounter issues, we recommend first consulting the [Troubleshooting](./troubleshooting.md) section.
+
+If your issue persists, please open a detailed issue on [Github](https://github.com/pydantic/logfire-helm-chart/issues), including:
+
+* Chart version
+* Kubernetes version
+* A sanitized copy of your ```values.yaml```
+* Relevant logs or error messages
+
+For commercial or enterprise support, contact [our sales team](mailto:[email protected]).

docs/self-hosted/installation.md renamed to docs/reference/self-hosted/installation.md

@@ -0,0 +1,101 @@
+# Self Hosted Introduction
+
+Logfire can be deployed on-premises using the official [Logifre Helm Chart](https://github.com/pydantic/logfire-helm-chart). This allows organizations the ability to fully manage their own data.
+
+This chart is included in our [Enterprise plan](../../enterprise.md). Contact us at [[email protected]](mailto:[email protected]) for details.
+
+### Key Benefits
+
+* **Simplified Deployment:** Install and manage the entire application stack with a single command.
+* **Flexible Configuration:** Easily adjust resource allocation, ingress settings, and authentication to your needs.
+* **Production-Ready Defaults:** Built-in settings for high availability, resource limits, and health checks.
+* **Repeatable & Versioned:** Manage your application deployment as code, ensuring consistency across environments.
+* **Compliance Friendly:** Leverage your own infrastructure to meet internal security standards.
+
+## System Requirements
+
+**Logfire** has been built from the ground up to be horizontally scalable. The self-hosted version shares the same code as the public deployment, and so is able to scale to high volumes of traffic.
+
+With that in mind, here are some minimum requirements that you will need to deploy logfire self-hosted:
+
+- A **Kubernetes** Cluster version `1.32` or greater
+- A **PostgreSQL** Database version `16` or greater
+- **Object Storage** such as Amazon S3, Azure Blob Storage or Google Cloud Storage
+- At least `512GB` or more local SSD scratch disk for ingest, compaction and caching
+- A **DNS/Hostname** to serve Logfire on. This does not need to be Internet accessible, but will need to be accessed over HTTP from any client.
+- An **Identity Provider** for Authenticating Users such as Github, Google or Microsoft.  **Logfire** uses [Dex for authentication](https://dexidp.io/docs/connectors/)
+
+Please view [installation](./installation.md) to find out how each of these are used.
+
+## Client Configuration Instructions
+
+After setting up the chart, you can send data to your **Logfire** Self-hosted instance by specifying the base url in advanced options:
+
+```python
+import logfire
+
+logfire.configure(
+    ..., # other options
+    advanced=logfire.AdvancedOptions(base_url="https://<your_logfire_hostname>")
+)
+```
+
+## Service Architecture
+
+The Self-hosted deployment has a number of interdependent services that work to run logfire.  Each component can be scaled independently of others depending on the utilisation of the system.
+
+### Service Dependency Diagram
+
+```mermaid
+graph
+    %% Entry point
+    LS[logfire-service:8080]
+
+    %% Core services
+    LB[logfire-backend:8000]
+    RD[logfire-redis:6379]
+    FIA[logfire-ff-ingest:8012]
+    FQA[logfire-ff-query-api:8011]
+    FCC[logfire-ff-cache:9001]
+    MW[logfire-maintenance-worker]
+
+    OS[(Object Storage)]
+    PG[(Postgres DB)]
+
+    %% Connections from entry point
+    LS --> LB
+    LS --> FIA
+
+    FQA --> FCC
+    FQA --> PG
+    FQA --> RD
+    FQA --> OS
+
+    LB --> FQA
+    LB --> RD
+
+    FIA --> PG
+    FIA --> RD
+    FIA --> OS
+
+    FCC --> OS
+
+    MW --> PG
+    MW --> OS
+
+
+```
+
+### Service Descriptions
+
+#### Entry Point
+- `logfire-service` (Port 8080): Main entry point for the system
+
+#### Core Services
+- `logfire-backend` (Port 8000): Backend service handling business logic, frontend and authentication
+- `logfire-ff-ingest` (Port 8012): API for data ingestion
+- `logfire-ff-query-api` (Port 8011): API for querying data
+- `logfire-ff-maintenance-worker`: Maintenance Jobs
+- `logfire-ff-compaction-worker`: Compaction Jobs
+- `logfire-redis`: Live query streaming and autocomplete cache
+- `logfire-ff-cache` (Port 9001 via `logfire-ff-conhash-cache` consistent hashing): Cache service

docs/self-hosted/playground.md renamed to docs/reference/self-hosted/local-quickstart.md

@@ -2,7 +2,7 @@
 
 **Logfire** is designed to be horizontally scalable, and can handle a lot of traffic. Depending on your usage patterns, however, you may be required to scale certain pods in order to maintain performance.
 
-Please use the [architecture](./architecture.md) diagram as reference.
+Please use the [architecture](./overview.md#service-architecture) diagram as reference.
 
 ## PostgreSQL Configuration