Quick Start

Get AsaHome Cloud running in minutes with Docker.

Prerequisites

Before you begin, ensure you have:

• Docker and Docker Compose installed
• Node.js 20+ (for local development without Docker)
• PostgreSQL 16+ (if running database separately)

Option 1: Using Docker (Recommended)

The fastest way to get started is with Docker Compose.

1. Clone the Repository

git clone <repository-url>
cd asahome-cloud

2. Run Initial Setup

make setup

This command will:

• Copy env.example to .env
• Generate a secure JWT secret
• Create necessary directories

3. Configure Environment

Edit the .env file with your settings:

nano .env

At minimum, update these values:

# Security - MUST change in production
JWT_SECRET=your-strong-random-secret-here

# Database
DB_PASSWORD=your-secure-password

# CORS - Add your app domains
CORS_ORIGINS=https://app.asahome.io,http://localhost:3000

Security

Never use default secrets in production. Generate a secure secret with:

openssl rand -base64 32

4. Start All Services

make up

This starts:

• PostgreSQL database
• NestJS application server
• Nginx reverse proxy

5. Verify Installation

make health

Or manually check the API:

curl http://localhost/api/v1/health

Expected response:

{
  "status": "ok",
  "timestamp": "2024-01-15T10:30:00.000Z",
  "service": "asahome-cloud"
}

Option 2: Local Development

For development without Docker containers.

1. Install Dependencies

npm install

2. Set Up Environment

cp env.example .env

3. Start PostgreSQL

You can use Docker just for the database:

docker run -d \
  --name asahome-postgres \
  -p 5432:5432 \
  -e POSTGRES_PASSWORD=postgres \
  -e POSTGRES_DB=asahome_cloud \
  postgres:16-alpine

4. Run Migrations

npm run migration:run

5. Start Development Server

npm run start:dev

The API will be available at http://localhost:3000/api/v1

Makefile Commands

Common operations are available via Make:

Command	Description
make setup	Initial project setup
make dev	Start development environment
make up	Start all containers
make down	Stop all containers
make logs	View all logs
make logs-app	View application logs only
make health	Check service health
make shell-db	Open PostgreSQL shell
make test	Run tests
make clean	Remove containers and volumes

Project Structure

After setup, you'll have:

asahome-cloud/
├── docker-compose.yml    # Container orchestration
├── Makefile              # Development commands
├── .env                  # Environment variables
├── nginx/                # Nginx configuration
│   └── conf.d/
│       └── default.conf
├── src/                  # Application source code
│   ├── auth/             # Authentication module
│   ├── devices/          # Device management
│   ├── websocket/        # WebSocket gateway
│   └── ...
└── package.json          # Node.js dependencies

What's Next?

Now that AsaHome Cloud is running:

1. Configure Environment - Fine-tune settings for your environment
2. Authentication Guide - Learn about JWT token flow
3. WebSocket Tunnel - Set up real-time device communication
4. API Reference - Explore available endpoints

Troubleshooting

Port Already in Use

# Check what's using port 80
lsof -i :80

# Or use a different port in docker-compose.yml

Database Connection Failed

# Check if PostgreSQL is running
docker-compose ps

# View database logs
make logs-db

Permission Denied

# Ensure Docker daemon is running
sudo systemctl start docker

# Add user to docker group
sudo usermod -aG docker $USER

For more solutions, see Troubleshooting.