Quickstart Guide

Overview

This guide will walk you through setting up Happy Habitat from scratch, including database configuration, backend setup, frontend deployment, and creating your first admin account.

This quickstart assumes you’re setting up a development environment. For production deployment, see the production notes at the end of this guide.

Prerequisites

Before you begin, ensure you have the following installed:

.NET 8.0 SDK: Download here
Node.js 18+: Download here
SQL Server 2019+: Download Express or use an existing instance
Git: For cloning the repository

Step 1: Clone the Repository

git clone <repository-url>
cd happy-habitat

The repository contains two main folders:

happy-habitat-backend/: .NET backend application
happy-habitat-frontend/: Angular frontend application

Step 2: Configure the Database

Create the Database

Happy Habitat uses SQL Server with Windows Authentication by default. You can configure SQL Server authentication if needed.

Update Connection String

Open happy-habitat-backend/HappyHabitat.API/appsettings.json and configure the database connection:

{
  "ConnectionStrings": {
    "DefaultConnection": "Server=(local);Database=HappyHabitat;Trusted_Connection=True;TrustServerCertificate=True;"
  }
}

For SQL Server authentication, use:

"DefaultConnection": "Server=(local);Database=HappyHabitat;User Id=youruser;Password=yourpassword;TrustServerCertificate=True;"

Configure Database Recreation (Development Only)

In appsettings.json, you can enable automatic database recreation for development:

{
  "Database": {
    "RecreateOnStartup": false
  }
}

Set RecreateOnStartup to true ONLY in development if you want the database dropped and recreated on each startup. This is useful for testing but will delete all data. Never set this to true in production - the application will refuse to start.

Apply Database Migrations

Navigate to the backend directory and run migrations:

cd happy-habitat-backend
dotnet ef database update -p HappyHabitat.Infrastructure -s HappyHabitat.API

This creates the database schema with all required tables.

Step 3: Configure the Backend

JWT Configuration

Set JWT Secret Key

In development, a default JWT key is provided. For production, you MUST set a secure key:Development (appsettings.json):

{
  "Jwt": {
    "Key": "YourSuperSecretKeyThatShouldBeAtLeast32CharactersLong!",
    "Issuer": "HappyHabitat",
    "Audience": "HappyHabitatUsers"
  }
}

In production, you must configure a unique, secure JWT key. The application will fail to start if you use the default key in production.

Configure CORS

For development, the backend allows localhost:4200 by default. For production, configure allowed origins:

{
  "Cors": {
    "Origins": "https://yourdomain.com;https://app.yourdomain.com"
  }
}

Separate multiple origins with semicolons (;).

Run the Backend

cd HappyHabitat.API
dotnet run

The backend will:

Apply any pending database migrations
Seed initial data (roles, vehicle types, ticket categories)
Create the default admin user
Start listening on http://localhost:5080

Swagger documentation is available at http://localhost:5080 when running in development mode.

Initial Admin Account

The system automatically creates a default admin account during first startup:

Username: elgrandeahc
Password: abc123
Email: [email protected]
Role: System Administrator

Change the default admin password immediately after first login, especially in production environments!

Step 4: Set Up the Frontend

Install Dependencies

cd happy-habitat-frontend
npm install

Configure API Endpoint

The frontend is pre-configured to connect to http://localhost:5080/api.To change this, edit src/environments/environment.ts:

export const environment = {
  production: false,
  apiUrl: 'http://localhost:5080/api',
  apiVersion: 'v1',
  appName: 'Happy Habitat',
  appVersion: '0.0.0',
  logging: {
    level: LogLevel.DEBUG,
    enableConsole: true,
    enableRemote: false,
    enableStackTraces: true
  },
  auth: {
    useMockAuth: false
  }
};

Start the Development Server

npm start

The frontend will be available at http://localhost:4200.

Access the Application

Open your browser and navigate to http://localhost:4200.

Use the default credentials:

Username: elgrandeahc
Password: abc123

Explore the Dashboard

After login, you’ll see the system administrator dashboard with access to:

Community management
User administration
System configuration
Reports and analytics

Step 6: Create Your First Community

Now that you’re logged in as a system administrator:

Navigate to Communities

From the admin dashboard, go to Communities > Add New Community.

Fill in Community Details

Provide the following information:

Name (Nombre): Your community name
Description (Descripcion): Brief description
Address (Direccion): Physical address
Contact: Main contact name
Email: Community email
Phone: Contact phone number
Type (TipoComunidad): e.g., “Condominium”, “Apartment Complex”
Number of Units (CantidadViviendas): Total residential units

Configure Community Settings

After creation, configure community-specific settings:

Pricing structures (CommunityPrices)
Custom configurations (CommunityConfigurations)
Service providers (CommunityProviders)

Seeded Data

The initial seeder (InitialSeeder.cs:20) automatically creates:

User Roles

SYSTEM_ADMIN: System Administrator
ADMIN_COMPANY: Company Administrator
COMITEE_MEMBER: Committee Member
RESIDENT: Resident
RENTER: Tenant
VIGILANCE: Security Personnel

Vehicle Types

Car
Motorcycle
Truck
SUV
Van

Ticket Statuses

Nuevo (New)
En revisión (Under Review)
En investigación (Under Investigation)
En proceso (In Progress)
Cancelado (Cancelled)
Resuelto (Resolved)

Development Tools

Swagger API Documentation

When running in development mode, access interactive API documentation at:

http://localhost:5080

Swagger includes JWT Bearer authentication. Click Authorize, enter Bearer <your-token>, and test authenticated endpoints.

Dummy Data Seeder

In development mode, the DummySeeder runs automatically to populate test data. To disable this, comment out lines 270-275 in Program.cs:270.

Running Seed Only

To run database migrations and seeders without starting the server:

dotnet run --seed-only

Production Deployment

Before deploying to production, ensure you configure these critical settings:

Required Production Configuration

JWT Key: Set a strong, unique secret key

"Jwt": {
  "Key": "<generate-a-secure-random-key-at-least-32-characters>"
}

CORS Origins: Specify your frontend domain(s)

"Cors": {
  "Origins": "https://yourdomain.com"
}

Database Recreation: MUST be false
```
"Database": {
  "RecreateOnStartup": false
}
```
The application will refuse to start if this is true in production (see Program.cs:248-252).
Connection String: Use secure credentials
- Consider using environment variables or Azure Key Vault
- Enable SSL/TLS for database connections
HTTPS: Enable HTTPS redirection (automatically enabled in production, see Program.cs:220-223)

Environment Variables

You can override appsettings.json values using environment variables:

Jwt__Key="your-production-key"
Cors__Origins="https://yourdomain.com"
ConnectionStrings__DefaultConnection="your-connection-string"

Build for Production

Backend:

dotnet publish -c Release -o ./publish

Frontend:

ng build --configuration production

The built files will be in dist/happy-habitat/.

Next Steps

Architecture Overview

Learn about the system architecture and design patterns

User Management

Learn how to create and manage users and roles

Community Setup

Configure communities, amenities, and settings

API Reference

Explore the REST API endpoints

Troubleshooting

Database connection fails

Verify SQL Server is running
Check connection string in appsettings.json
Ensure Windows Authentication is enabled or use SQL auth
Verify firewall allows SQL Server connections (port 1433)

CORS errors in browser

Ensure backend is running on the expected port (5080)
Check Cors:Origins configuration in appsettings.json
Verify frontend apiUrl in environment.ts matches backend URL

JWT authentication fails

Verify Jwt:Key is set correctly in backend configuration
Check token expiration (configured in JwtService.cs)
Clear browser local storage and try logging in again

Migration errors

Ensure Entity Framework tools are installed: dotnet tool install --global dotnet-ef
Run migrations from the correct directory
Check database permissions for the connection user

Getting Started

Core Features

User Guides

Deployment

Overview

Prerequisites

Step 1: Clone the Repository

Step 2: Configure the Database

Create the Database

Step 3: Configure the Backend

JWT Configuration

Run the Backend

Initial Admin Account

Step 4: Set Up the Frontend

Step 6: Create Your First Community

Seeded Data

User Roles

Vehicle Types

Ticket Categories

Ticket Statuses

Development Tools

Swagger API Documentation

Dummy Data Seeder

Running Seed Only

Production Deployment

Required Production Configuration

Environment Variables

Build for Production

Next Steps

Architecture Overview

User Management

Community Setup

API Reference

Troubleshooting

Build docs developers (and LLMs) love

Getting Started

Core Features

User Guides

Deployment

​Overview

​Prerequisites

​Step 1: Clone the Repository

​Step 2: Configure the Database

​Create the Database

​Step 3: Configure the Backend

​JWT Configuration

​Run the Backend

​Initial Admin Account

​Step 4: Set Up the Frontend

​Step 5: First Login

​Step 6: Create Your First Community

​Seeded Data

​User Roles

​Vehicle Types

​Ticket Categories

​Ticket Statuses

​Development Tools

​Swagger API Documentation

​Dummy Data Seeder

​Running Seed Only

​Production Deployment

​Required Production Configuration

​Environment Variables

​Build for Production

​Next Steps

Architecture Overview

User Management

Community Setup

API Reference

​Troubleshooting

Build docs developers (and LLMs) love

Overview

Prerequisites

Step 1: Clone the Repository

Step 2: Configure the Database

Create the Database

Step 3: Configure the Backend

JWT Configuration

Run the Backend

Initial Admin Account

Step 4: Set Up the Frontend

Step 5: First Login

Step 6: Create Your First Community

Seeded Data

User Roles

Vehicle Types

Ticket Categories

Ticket Statuses

Development Tools

Swagger API Documentation

Dummy Data Seeder

Running Seed Only

Production Deployment

Required Production Configuration

Environment Variables

Build for Production

Next Steps

Troubleshooting