Installation Guide - gabrielmaialva33/innkeeper GitHub Wiki

๐Ÿš€ Installation Guide

Complete setup instructions for Innkeeper development and production environments

๐Ÿ“‹ Prerequisites

Before installing Innkeeper, ensure you have the following prerequisites installed on your system:

System Requirements

  • Node.js >= 20.6.0 (LTS recommended)
  • PostgreSQL >= 14.0
  • Redis >= 6.0
  • Git >= 2.30.0

Package Manager

  • pnpm >= 8.0.0 (recommended) or npm >= 9.0.0

Optional (for production)

  • Docker >= 20.10.0
  • Docker Compose >= 2.0.0
  • Nginx >= 1.20.0 (for reverse proxy)

๐Ÿ› ๏ธ Development Setup

1. Clone the Repository

# Clone the repository
git clone https://github.com/gabrielmaialva33/innkeeper.git
cd innkeeper

# Or using SSH
git clone [email protected]:gabrielmaialva33/innkeeper.git
cd innkeeper

2. Install Dependencies

# Install all dependencies
pnpm install

# Or using npm
npm install

3. Environment Configuration

# Copy the example environment file
cp .env.example .env

# Generate application key
node ace generate:key

4. Configure Environment Variables

Edit the .env file with your configuration:

# Application
NODE_ENV=development
PORT=3333
HOST=localhost
LOG_LEVEL=info
APP_KEY=your-generated-app-key
APP_NAME=Innkeeper

# Database
DB_HOST=127.0.0.1
DB_PORT=5432
DB_USER=postgres
DB_PASSWORD=your-password
DB_DATABASE=innkeeper_dev

# Redis
REDIS_HOST=127.0.0.1
REDIS_PORT=6379
REDIS_PASSWORD=

# Session
SESSION_DRIVER=redis

# Mail (for development)
MAIL_MAILER=smtp
MAIL_HOST=localhost
MAIL_PORT=1025
MAIL_USERNAME=
MAIL_PASSWORD=
MAIL_ENCRYPTION=false

# File Storage
DRIVE_DISK=local

5. Database Setup

# Create the database
createdb innkeeper_dev

# Run migrations
node ace migration:run

# Seed the database (optional)
node ace db:seed

6. Start the Development Server

# Start the development server
pnpm run dev

# Or using npm
npm run dev

Your application will be available at http://localhost:3333

๐Ÿณ Docker Development Setup

For a containerized development environment:

1. Using Docker Compose

# Clone the repository
git clone https://github.com/gabrielmaialva33/innkeeper.git
cd innkeeper

# Copy environment file
cp .env.example .env

# Start all services
docker-compose up -d

# Run migrations
docker-compose exec app node ace migration:run

# Seed the database (optional)
docker-compose exec app node ace db:seed

2. Docker Services

The Docker setup includes:

  • App Container: Node.js application
  • PostgreSQL: Database server
  • Redis: Cache and session store
  • Mailhog: Email testing (development only)

๐Ÿญ Production Setup

1. Server Requirements

Minimum Requirements:

  • 2 CPU cores
  • 4GB RAM
  • 20GB SSD storage
  • Ubuntu 20.04+ or CentOS 8+

Recommended:

  • 4+ CPU cores
  • 8GB+ RAM
  • 50GB+ SSD storage
  • Load balancer for high availability

2. System Dependencies

# Update system packages
sudo apt update && sudo apt upgrade -y

# Install Node.js (using NodeSource repository)
curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt-get install -y nodejs

# Install PostgreSQL
sudo apt install postgresql postgresql-contrib

# Install Redis
sudo apt install redis-server

# Install Nginx
sudo apt install nginx

# Install PM2 for process management
npm install -g pm2

3. Database Configuration

# Switch to postgres user
sudo -u postgres psql

# Create database and user
CREATE DATABASE innkeeper_prod;
CREATE USER innkeeper WITH ENCRYPTED PASSWORD 'your-secure-password';
GRANT ALL PRIVILEGES ON DATABASE innkeeper_prod TO innkeeper;
\q

4. Application Deployment

# Clone repository
git clone https://github.com/gabrielmaialva33/innkeeper.git
cd innkeeper

# Install dependencies
npm ci --only=production

# Copy and configure environment
cp .env.example .env
# Edit .env with production values

# Generate app key
node ace generate:key

# Build the application
npm run build

# Run migrations
node ace migration:run --force

# Start with PM2
pm2 start ecosystem.config.js
pm2 save
pm2 startup

5. Nginx Configuration

Create /etc/nginx/sites-available/innkeeper:

server {
    listen 80;
    server_name your-domain.com;

    location / {
        proxy_pass http://localhost:3333;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection 'upgrade';
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_cache_bypass $http_upgrade;
    }
}

Enable the site:

sudo ln -s /etc/nginx/sites-available/innkeeper /etc/nginx/sites-enabled/
sudo nginx -t
sudo systemctl reload nginx

๐Ÿ”’ SSL/TLS Setup

Using Certbot (Let's Encrypt)

# Install Certbot
sudo apt install certbot python3-certbot-nginx

# Obtain SSL certificate
sudo certbot --nginx -d your-domain.com

# Auto-renewal (already configured by default)
sudo systemctl status certbot.timer

๐Ÿ”ง Configuration Options

Environment Variables Reference

Variable Description Default Required
NODE_ENV Application environment development Yes
PORT Server port 3333 No
HOST Server host localhost No
APP_KEY Application encryption key - Yes
DB_HOST Database host 127.0.0.1 Yes
DB_PORT Database port 5432 No
DB_USER Database username - Yes
DB_PASSWORD Database password - Yes
DB_DATABASE Database name - Yes
REDIS_HOST Redis host 127.0.0.1 Yes
REDIS_PORT Redis port 6379 No
SESSION_DRIVER Session storage driver redis No

Multi-Tenant Configuration

# Multi-tenant settings
TENANT_MODE=subdomain  # or 'domain' or 'path'
DEFAULT_TENANT=demo
TENANT_CACHE_TTL=3600

๐Ÿงช Verification

Health Check

# Check application health
curl http://localhost:3333/health

# Expected response
{
  "status": "ok",
  "timestamp": "2024-01-01T00:00:00.000Z",
  "uptime": 123.456,
  "database": "connected",
  "redis": "connected"
}

Database Connection

# Test database connection
node ace db:check

# Run a simple query
node ace tinker
# In tinker console:
await Database.rawQuery('SELECT version()')

๐Ÿšจ Troubleshooting

Common Issues

Port Already in Use

# Find process using port 3333
lsof -i :3333

# Kill the process
kill -9 <PID>

Database Connection Issues

# Check PostgreSQL status
sudo systemctl status postgresql

# Check connection
psql -h localhost -U postgres -d innkeeper_dev

Redis Connection Issues

# Check Redis status
sudo systemctl status redis

# Test Redis connection
redis-cli ping

Permission Issues

# Fix file permissions
sudo chown -R $USER:$USER /path/to/innkeeper
chmod -R 755 /path/to/innkeeper

Log Files

  • Application logs: tmp/logs/app.log
  • Database logs: /var/log/postgresql/
  • Nginx logs: /var/log/nginx/
  • PM2 logs: ~/.pm2/logs/

๐Ÿ“š Next Steps

After successful installation:

  1. Quick Start Guide - Get your first hotel property running
  2. Configuration Guide - Detailed configuration options
  3. System Architecture - Understand the system design
  4. Development Guide - Start developing with Innkeeper

๐Ÿ†˜ Need Help?

โ† Back to Wiki Home | Next: Quick Start โ†’

โš ๏ธ **GitHub.com Fallback** โš ๏ธ