Getting Started
Deploy Idenplane in 30 seconds with Docker Compose, or build from source for full control.
Idenplane is a self-hosted, open-source identity and access management (IAM) server. This guide gets you from zero to a running instance two ways: the Docker Compose quick start (recommended — about 30 seconds) or a build from source for full control. The quick start needs only Docker and Docker Compose; building from source also needs Node.js 22+ and PostgreSQL 16+. Once it’s up you’ll have the admin console, standards-compliant OAuth 2.0 / OIDC / SAML endpoints, and health and metrics endpoints ready to use.
Docker Quick Start
Recommended
The fastest way to get Idenplane running. Requires only Docker and Docker Compose.
# Download the docker-compose file
curl -o docker-compose.yml \
https://raw.githubusercontent.com/idenplane/idenplane/main/docker-compose.yml
# Start Idenplane
docker compose up -dThat's it! Idenplane will start with PostgreSQL and be ready in about 30 seconds.
Verify your installation
Confirm the server is healthy, then sign in to the admin console:
# Health check — returns HTTP 200 with a JSON status payload
curl http://localhost:3000/health
# Then open the admin console in your browser
open http://localhost:3000/console
Sign in with the default admin / admin credentials, then change the password immediately (see Configuration). If the health check fails, head to Troubleshooting.
Available Endpoints
Once running, these endpoints are available on your server:
| URL | Description |
|---|---|
http://localhost:3000/console | Admin Console |
http://localhost:3000/api | Swagger API Docs |
http://localhost:3000/health | Health Check |
http://localhost:3000/metrics | Prometheus Metrics |
Default Credentials
Change these before exposing Idenplane to the internet.
| Field | Default Value |
|---|---|
| Username | admin |
| Password | admin |
| API Key | ADMIN_API_KEY from your .env |
Build from Source
Prerequisites
# Clone the repository
git clone https://github.com/idenplane/idenplane.git
cd Idenplane
# Install dependencies
npm install
cd admin-ui && npm install && cd ..
# Configure environment
cp .env.example .env
# Edit .env with your DATABASE_URL
# Setup database
npm run prisma:generate
npm run prisma:migrate
npm run prisma:seed # Optional: sample data
# Build & start
npm run build:all
npm run start:prodDatabase Helper Commands
| Command | Description |
|---|---|
npm run prisma:generate | Regenerate Prisma client |
npm run prisma:migrate | Apply pending migrations |
npm run prisma:seed | Seed with test data |
npm run db:setup | Generate + migrate + seed (all-in-one) |
Troubleshooting
- Port already in use: another process is on port 3000 — stop it, or change Idenplane’s port in your
.env/ compose file. - Database connection errors: make sure PostgreSQL is reachable and
DATABASE_URLis correct before the server starts. - Console not loading: give the container a few seconds to finish database migrations, then retry the health check.