Skip to content

Commit 7157b8f

Browse files
JeromeBuJeromeBu
committed
feat: add keycloak docker-compose example
1 parent 9de6b21 commit 7157b8f

File tree

6 files changed

+1624
-1
lines changed

6 files changed

+1624
-1
lines changed

‎deployment-examples/keycloak-docker-compose/.env.sample‎

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,19 @@
1+
# Database Configuration
2+
POSTGRES_DB=keycloak
3+
POSTGRES_USER=keycloak
4+
POSTGRES_PASSWORD=change_me_in_production
5+
6+
# Keycloak Admin Configuration
7+
KEYCLOAK_ADMIN=admin
8+
KEYCLOAK_ADMIN_PASSWORD=change_me_in_production
9+
10+
# Keycloak Hostname Configuration
11+
# Set these to your domain in production
12+
KC_HOSTNAME=localhost
13+
KC_HOSTNAME_PORT=8082
14+
15+
# Port Configuration
16+
KEYCLOAK_PORT=8082
17+
18+
# Logging Configuration
19+
KC_LOG_LEVEL=INFO

‎deployment-examples/keycloak-docker-compose/README.md‎

Lines changed: 315 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,315 @@
1+
# Simple Keycloak with Docker Compose
2+
3+
This directory contains a production-ready Keycloak setup using Docker Compose with PostgreSQL as the database backend and Nginx as a reverse proxy. The configuration is designed for simple email/password authentication with minimal user data requirements.
4+
5+
**Note**: This setup uses port 8092 for Keycloak to avoid conflicts with other services in the catalogi project (ports 8090-8091 are used by the main deployment example).
6+
7+
## ⚠️ Disclaimer
8+
9+
This Keycloak setup is provided as-is and comes with the following important considerations:
10+
11+
1. **Security**: While this configuration includes basic security measures, it is your responsibility to:
12+
13+
- Implement proper security measures for your specific use case
14+
- Regularly update dependencies and apply security patches
15+
- Configure appropriate password policies and security settings
16+
- Set up proper monitoring and alerting
17+
18+
2. **Production Use**: Before deploying to production:
19+
20+
- Review and customize all security settings
21+
- Set up proper backup and disaster recovery procedures
22+
- Configure appropriate logging and monitoring
23+
- Test thoroughly in a staging environment
24+
- Ensure compliance with your organization's security policies
25+
26+
3. **Maintenance**: Regular maintenance is required:
27+
28+
- Keep Docker images updated
29+
- Monitor database size and performance
30+
- Review and rotate credentials regularly
31+
- Monitor system logs for security issues
32+
33+
4. **Support**: This is a community-maintained example:
34+
- No official support is provided
35+
- Issues should be reported through the project's issue tracker
36+
- For production deployments, consider consulting with security experts
37+
38+
## Features
39+
40+
- **Production-ready**: Uses PostgreSQL database backend instead of development H2 database
41+
- **Nginx Reverse Proxy**: Secure HTTPS termination and proper header handling
42+
- **Simple authentication**: Email and password only, no additional user attributes required
43+
- **Easy setup**: Single command deployment with Docker Compose
44+
- **Health checks**: Built-in health monitoring for all services
45+
- **Configurable**: Environment variables for easy customization
46+
- **Secure defaults**: Brute force protection and other security features enabled
47+
48+
## Quick Start
49+
50+
1. **Clone and navigate to the directory**:
51+
52+
```bash
53+
cd deployment-examples/keycloak-docker-compose
54+
```
55+
56+
2. **Create environment file**:
57+
58+
```bash
59+
cp .env.sample .env
60+
```
61+
62+
3. **Edit environment variables** (important for production):
63+
64+
```bash
65+
nano .env
66+
```
67+
68+
**⚠️ Important**: Change the default passwords in production:
69+
70+
- `POSTGRES_PASSWORD`
71+
- `KEYCLOAK_ADMIN_PASSWORD`
72+
- `KC_HOSTNAME` (set to your domain)
73+
74+
4. **Start the services**:
75+
76+
```bash
77+
docker-compose up -d
78+
```
79+
80+
5. **Wait for services to be ready** (takes 1-2 minutes):
81+
82+
```bash
83+
docker-compose logs -f keycloak
84+
```
85+
86+
6. **Access Keycloak**:
87+
- **Admin Console**: http://localhost:8092/admin
88+
- **Login**: Use the admin credentials from your `.env` file
89+
- **User Realm**: http://localhost:8092/realms/simple
90+
91+
## Configuration
92+
93+
### Environment Variables
94+
95+
| Variable | Default | Description |
96+
| ------------------------- | ------------------------- | ------------------------------------ |
97+
| `POSTGRES_DB` | `keycloak` | PostgreSQL database name |
98+
| `POSTGRES_USER` | `keycloak` | PostgreSQL username |
99+
| `POSTGRES_PASSWORD` | `change_me_in_production` | PostgreSQL password |
100+
| `KEYCLOAK_ADMIN` | `admin` | Keycloak admin username |
101+
| `KEYCLOAK_ADMIN_PASSWORD` | `change_me_in_production` | Keycloak admin password |
102+
| `KC_HOSTNAME` | `localhost` | Keycloak hostname |
103+
| `KC_HOSTNAME_PORT` | `8082` | Keycloak port |
104+
| `KEYCLOAK_PORT` | `8082` | Host port for Keycloak |
105+
| `KC_LOG_LEVEL` | `INFO` | Log level (DEBUG, INFO, WARN, ERROR) |
106+
| `NGINX_HOSTNAME` | `localhost` | Nginx hostname |
107+
| `NGINX_HTTP_PORT` | `80` | Nginx HTTP port |
108+
| `NGINX_HTTPS_PORT` | `443` | Nginx HTTPS port |
109+
110+
### Realm Configuration
111+
112+
The setup includes a pre-configured realm called "simple" with:
113+
114+
- **Email as username**: Users register and login with email only
115+
- **No additional attributes**: Only email and password required
116+
- **Registration enabled**: Users can self-register
117+
- **Password reset enabled**: Users can reset their passwords
118+
- **Brute force protection**: Enabled for security
119+
- **Sample client**: `my-app` client pre-configured for localhost:3000
120+
121+
### Client Configuration
122+
123+
A sample client `my-app` is pre-configured with:
124+
125+
- **Client ID**: `my-app`
126+
- **Public client**: No client secret required
127+
- **Redirect URIs**: `http://localhost:3000/*`, `https://localhost:3000/*`, `http://localhost:8090/*`
128+
- **Web Origins**: `http://localhost:3000`, `https://localhost:3000`, `http://localhost:8090`
129+
130+
## Production Deployment
131+
132+
### Security Checklist
133+
134+
1. **Change default passwords** in `.env` file
135+
2. **Set proper hostname** (`KC_HOSTNAME`) to your domain
136+
3. **Use HTTPS** in production (configure reverse proxy)
137+
4. **Secure database** with strong password and network isolation
138+
5. **Regular backups** of PostgreSQL data
139+
6. **Update images** regularly for security patches
140+
141+
### Sample Production Environment
142+
143+
```bash
144+
# Database Configuration
145+
POSTGRES_DB=keycloak_prod
146+
POSTGRES_USER=keycloak_user
147+
POSTGRES_PASSWORD=your_very_secure_password_here
148+
149+
# Keycloak Admin Configuration
150+
KEYCLOAK_ADMIN=admin
151+
KEYCLOAK_ADMIN_PASSWORD=your_admin_password_here
152+
153+
# Keycloak Hostname Configuration
154+
KC_HOSTNAME=auth.yourdomain.com
155+
KC_HOSTNAME_PORT=443
156+
157+
# Port Configuration
158+
KEYCLOAK_PORT=8082
159+
160+
# Logging Configuration
161+
KC_LOG_LEVEL=WARN
162+
```
163+
164+
### Reverse Proxy Setup
165+
166+
For production, use a reverse proxy (nginx, Traefik, etc.) to handle HTTPS:
167+
168+
```nginx
169+
server {
170+
listen 443 ssl;
171+
server_name auth.yourdomain.com;
172+
173+
# SSL configuration
174+
ssl_certificate /path/to/cert.pem;
175+
ssl_certificate_key /path/to/key.pem;
176+
177+
location / {
178+
proxy_pass http://localhost:8082;
179+
proxy_set_header Host $host;
180+
proxy_set_header X-Real-IP $remote_addr;
181+
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
182+
proxy_set_header X-Forwarded-Proto $scheme;
183+
}
184+
}
185+
```
186+
187+
## Managing the Setup
188+
189+
### Useful Commands
190+
191+
```bash
192+
# Start services
193+
docker-compose up -d
194+
195+
# Stop services
196+
docker-compose down
197+
198+
# View logs
199+
docker-compose logs -f keycloak
200+
docker-compose logs -f postgres
201+
202+
# Restart services
203+
docker-compose restart
204+
205+
# Update images
206+
docker-compose pull
207+
docker-compose up -d
208+
209+
# Backup database
210+
docker-compose exec postgres pg_dump -U keycloak keycloak > backup.sql
211+
212+
# Restore database
213+
docker-compose exec -i postgres psql -U keycloak keycloak < backup.sql
214+
```
215+
216+
### Health Checks
217+
218+
Both services include health checks:
219+
220+
- **PostgreSQL**: `pg_isready` command
221+
- **Keycloak**: HTTP health endpoint at `/health/ready`
222+
223+
Check service health:
224+
225+
```bash
226+
docker-compose ps
227+
```
228+
229+
## Troubleshooting
230+
231+
### Common Issues
232+
233+
1. **Services not starting**: Check logs with `docker-compose logs`
234+
2. **Database connection errors**: Ensure PostgreSQL is healthy first
235+
3. **Cannot access admin console**: Verify `KC_HOSTNAME` and port configuration
236+
4. **Login issues**: Check realm configuration and user creation
237+
238+
### Logs and Debugging
239+
240+
```bash
241+
# View all logs
242+
docker-compose logs
243+
244+
# Follow specific service logs
245+
docker-compose logs -f keycloak
246+
docker-compose logs -f postgres
247+
248+
# Enable debug logging
249+
# Set KC_LOG_LEVEL=DEBUG in .env and restart
250+
```
251+
252+
## Integration Example
253+
254+
### Basic OIDC Integration
255+
256+
```javascript
257+
// Example configuration for your application
258+
const oidcConfig = {
259+
issuer: "http://localhost:8082/realms/simple",
260+
clientId: "my-app",
261+
redirectUri: "http://localhost:3000/callback",
262+
scope: "openid email profile",
263+
};
264+
```
265+
266+
### User Registration Flow
267+
268+
1. User visits your application
269+
2. Redirected to Keycloak login page
270+
3. User clicks "Register"
271+
4. Enters email and password only
272+
5. Account created and user logged in
273+
6. Redirected back to your application
274+
275+
## Documentation
276+
277+
### Official Keycloak Documentation
278+
279+
- [Keycloak Documentation](https://www.keycloak.org/documentation)
280+
- [Keycloak Server Administration Guide](https://www.keycloak.org/docs/latest/server_admin/)
281+
- [Keycloak Securing Apps and Services Guide](https://www.keycloak.org/docs/latest/securing_apps/)
282+
- [Keycloak REST API](https://www.keycloak.org/docs-api/latest/rest-api/)
283+
- [Keycloak Docker Images](https://quay.io/repository/keycloak/keycloak)
284+
285+
### Keycloak Version
286+
287+
This setup uses Keycloak version 26.2.5. For specific version documentation:
288+
289+
- [Keycloak 26.2.5 Documentation](https://www.keycloak.org/docs/26.2.5/)
290+
291+
## Support
292+
293+
For Keycloak-specific issues, refer to the [official Keycloak documentation](https://www.keycloak.org/documentation).
294+
295+
For this setup specifically, check:
296+
297+
1. Docker and Docker Compose logs
298+
2. Environment variable configuration
299+
3. Network connectivity between services
300+
4. PostgreSQL data persistence
301+
302+
### Accessing Keycloak
303+
304+
With Nginx configured, you can access Keycloak through:
305+
306+
- **Development**:
307+
308+
- HTTP: http://localhost:8092/admin
309+
- HTTP: http://localhost:8092/realms/simple
310+
311+
- **Production**:
312+
- HTTPS: https://your-domain/admin
313+
- HTTPS: https://your-domain/realms/simple
314+
315+
Note: For production, ensure your domain is properly configured in the environment variables and SSL is handled at your infrastructure level.

0 commit comments

Comments
 (0)