Skip to main content

​
Get Up and Running Fast

This guide will get you from zero to a fully functional Bookify API in just a few minutes using Docker Compose.
Prerequisites: You only need Docker and Docker Compose installed. Everything else runs in containers.

​
Quick Start Steps

1

Clone the Repository

Clone the Bookify repository to your local machine:
git clone https://github.com/yourusername/bookify.git
cd bookify
2

Start the Application

Use Docker Compose to start all services (API, PostgreSQL, Redis, Keycloak, Seq):
docker-compose up -d
This command will:
  • Build the Bookify API Docker image
  • Start PostgreSQL database on port 4001
  • Start Redis cache on port 6379
  • Start Keycloak identity provider on port 18080
  • Start Seq logging server on ports 5341 and 8081
  • Start the Bookify API on port 5001 (HTTPS)
The first run will take a few minutes to download images and build the application. Subsequent starts will be much faster.
3

Verify Services are Running

Check that all containers are running:
docker-compose ps
You should see all services with status “Up”:
  • bookify.api
  • Bookify.Db (PostgreSQL)
  • Bookify.Identity (Keycloak)
  • Bookify.Seq (Logging)
  • Bookify.Redis (Cache)
4

Check API Health

Verify the API is healthy by checking the health endpoint:
curl -k https://localhost:5001/health
You should see a JSON response indicating all health checks passed:
{
  "status": "Healthy",
  "totalDuration": "00:00:00.0234567",
  "entries": {
    "npgsql": {
      "status": "Healthy"
    },
    "redis": {
      "status": "Healthy"
    },
    "keycloak": {
      "status": "Healthy"
    }
  }
}
Use -k flag with curl to bypass SSL certificate validation for local development.
5

Explore the API with Swagger

Open your browser and navigate to the Swagger UI:
https://localhost:5001/swagger
Your browser will warn about the self-signed certificate. Accept the warning to proceed (this is safe for local development).
You’ll see the interactive API documentation where you can explore and test all available endpoints.
6

Make Your First API Call

Search for available apartments using the search endpoint:
curl -k "https://localhost:5001/api/apartments?startDate=2026-04-01&endDate=2026-04-07"
This will return a list of available apartments for the specified date range:
[
  {
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "name": "Luxury Downtown Apartment",
    "description": "Beautiful apartment in the heart of the city",
    "price": {
      "amount": 150.00,
      "currency": "USD"
    },
    "address": {
      "country": "United States",
      "state": "California",
      "zipCode": "90001",
      "city": "Los Angeles",
      "street": "123 Main St"
    },
    "amenities": ["WiFi", "AirConditioning", "Parking"]
  }
]
On the first run in Development mode, the database is automatically seeded with sample apartment data, so you’ll see results immediately.

​
Access the Services

Once everything is running, you can access:
ServiceURLCredentials
Bookify APIhttps://localhost:5001N/A
Swagger UIhttps://localhost:5001/swaggerN/A
Keycloak Adminhttp://localhost:18080admin / admin
Seq Logshttp://localhost:8081N/A
PostgreSQLlocalhost:4001postgres / postgres
Redislocalhost:6379No password

​
Understanding the Docker Setup

The application uses two Docker Compose files: 
services:
  bookify.api:
    image: ${DOCKER_REGISTRY-}bookifyapi
    build:
      context: .
      dockerfile: src/Bookify.Api/Dockerfile

  bookify-db:
   image: postgres:latest

volumes:
  postgres_bookifydb:

​
Next Steps: Make a Booking

Now that your API is running, try creating a booking:
1

Get an Authentication Token

First, you’ll need to authenticate with Keycloak. Use the token endpoint:
curl -X POST "http://localhost:18080/realms/Bookify/protocol/openid-connect/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "client_id=bookify-auth-client" \
  -d "client_secret=rZjRoaaamQmVtluhM8RN227GqtKzzZg5" \
  -d "grant_type=client_credentials"
Save the access_token from the response.
2

Create a Booking

Use the token to reserve an apartment:
curl -k -X POST "https://localhost:5001/api/bookings" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "apartmentId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "userId": "3fa85f64-5717-4562-b3fc-2c963f66afa7",
    "startDate": "2026-04-01",
    "endDate": "2026-04-07"
  }'

​
Stopping the Application

When you’re done, stop all services: 
# Stop containers but keep data
docker-compose down

# Stop containers and remove volumes (clean slate)
docker-compose down -v

​
Troubleshooting

If you see errors about ports being in use, you can either:
  • Stop the conflicting service
  • Modify the port mappings in docker-compose.override.yml
Wait a few seconds for PostgreSQL to fully start. The API has automatic retry logic but may need a moment on first startup.
In Development mode, migrations are automatically applied on startup. Check the logs:
docker-compose logs bookify.api
Check logs for any service:
docker-compose logs -f bookify.api    # API logs
docker-compose logs -f bookify-db     # Database logs
docker-compose logs -f bookify-idp    # Keycloak logs
Or view structured logs in Seq at http://localhost:8081

​
What’s Next?

Now that you have Bookify running:

Build docs developers (and LLMs) love

Get started for freeTalk to us