Self-hosted headless initialization

[surekha3]

Describe your question

I've deployed self hosted langfuse and created org, project, users in langfuse UI. Can i now enable LANGFUSE_INIT* variables in my config. If so will it conflict as there is already one org existing

Langfuse Cloud or Self-Hosted?

Self-Hosted

If Self-Hosted

3.221.1

If Langfuse Cloud

No response

SDK and integration versions

No response

Pre-Submission Checklist

• I have checked for existing issues/discussions and consulted Langfuse AI.

[inkeep-ai-assistant[bot]]

Yes, you can enable LANGFUSE_INIT_* variables after already creating resources via the UI, but there are important considerations.

How Headless Initialization Works

Langfuse will automatically create the specified resources on startup only if they don't already exist. (1)

This means:

• If you set a new LANGFUSE_INIT_ORG_ID that differs from your existing organization's ID, Langfuse will create a new organization rather than reusing the existing one. (2)
• New users would then be assigned to this new organization, effectively splitting your instance into two separate organizations. (2)

To Avoid Conflicts

If you want headless initialization to work with your existing setup, you need to use the same IDs that were assigned to your existing organization and project when they were created via the UI. This way, Langfuse will recognize them as already existing and won't create duplicates.

Resource Dependencies

The resources depend on each other as follows: (1)

Organization
├── Project (part of organization)
│   └── API Keys (set for project)
└── User (owner of organization)

(1)

You can initialize an organization and user without initializing a project and API keys, but you cannot initialize a project without also initializing an organization. (1)

Important Note on User Roles

If you use headless initialization with automated access provisioning, be aware that the initialized user becomes OWNER of the organization but may only be MEMBER or VIEWER at the project level (depending on LANGFUSE_DEFAULT_PROJECT_ROLE). To ensure full project permissions, explicitly set: (3)

LANGFUSE_DEFAULT_PROJECT_ROLE=OWNER

(1) (4)

For more complex deployment scenarios with existing resources, the Organization Management API is recommended over headless initialization. (2)

📚 Sources:

1. Headless Initialization
2. Self-hosted headless initialization
3. Headless initialization creates org OWNER but project VIEWER (cannot create prompts)
4. Deployment Guide (v2)

---

Have another question? Just tag @inkeep.