littleshop/DOCKER-DEPLOYMENT.md

LittleShop Docker Deployment Guide

Overview

LittleShop is now fully containerized with Docker for easy deployment and management.

Quick Start

Local Development

# Build and run locally
./docker-build.sh

# Access the application
# http://localhost:5100

Production Deployment (Hostinger VPS)

# Deploy to Hostinger VPS
./docker-deploy-hostinger.sh

Architecture

Container Configuration

• Base Image: .NET 9.0 ASP.NET Core runtime
• Port: 5000 (internal), mapped to 5100 (host localhost only)
• User: Non-root user for security
• Health Check: Built-in health monitoring

Security Features

• ✅ Localhost-only binding (127.0.0.1:5100)
• ✅ Non-root container execution
• ✅ Minimal base image
• ✅ No unnecessary packages
• ✅ Environment variable configuration

Configuration

Environment Variables

Create a .env file from the template:

cp .env.production .env

Key configurations:

• JWT_SECRET_KEY - Authentication secret (pre-configured)
• SILVERPAY_* - Payment gateway settings (pre-configured)
• ROYALMAIL_* - Shipping integration (optional)
• TELEBOT_* - Bot integration (optional)

Volumes

The application uses three persistent volumes:

• littleshop_data - SQLite database
• littleshop_logs - Application logs
• littleshop_uploads - User uploaded files

Deployment Scripts

docker-build.sh

Local build and run script with options:

# Build only
./docker-build.sh --build-only

# Build and push to registry
./docker-build.sh --push --registry your-registry.com

# Build and run (default)
./docker-build.sh

docker-deploy-hostinger.sh

Automated deployment to Hostinger VPS:

1. Builds image locally
2. Saves as compressed tar
3. Transfers to server via SCP
4. Loads and runs on server
5. Verifies deployment

Docker Commands

Basic Operations

# Start containers
docker-compose up -d

# Stop containers
docker-compose down

# View logs
docker logs -f littleshop

# Restart container
docker-compose restart

# Shell access
docker exec -it littleshop /bin/bash

Monitoring

# Check status
docker-compose ps

# View resource usage
docker stats littleshop

# Health check
curl http://localhost:5100/api/catalog/products

Remote Access

SSH Tunnel for Admin Access

ssh -i ~/.ssh/hostinger_key -p 2255 -L 5100:127.0.0.1:5100 root@srv1002428.hstgr.cloud
# Then access: http://localhost:5100/Admin

Direct Server Commands

# Connect to server
ssh -i ~/.ssh/hostinger_key -p 2255 root@srv1002428.hstgr.cloud

# Navigate to app directory
cd /opt/docker/littleshop

# View logs
docker logs -f littleshop

# Restart
docker-compose restart

Nginx Integration (Optional)

To expose the application externally through nginx:

1. Create nginx configuration:

server {
    listen 80;
    server_name srv1002428.hstgr.cloud;

    location / {
        proxy_pass http://127.0.0.1:5100;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection keep-alive;
        proxy_set_header Host $host;
        proxy_cache_bypass $http_upgrade;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

2. Enable and reload nginx:

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

Backup and Restore

Backup Database

# On server
docker exec littleshop sqlite3 /app/data/littleshop-production.db ".backup /app/data/backup.db"
docker cp littleshop:/app/data/backup.db ./littleshop-backup-$(date +%Y%m%d).db

Restore Database

# Stop container
docker-compose down

# Copy backup
docker cp ./littleshop-backup.db littleshop:/app/data/littleshop-production.db

# Start container
docker-compose up -d

Troubleshooting

Container Won't Start

# Check logs
docker logs littleshop

# Check docker-compose logs
docker-compose logs

# Verify image
docker images | grep littleshop

Port Already in Use

# Check what's using port 5100
ss -tulpn | grep :5100

# Change port in docker-compose.yml
# ports:
#   - "127.0.0.1:5200:5000"

Database Issues

# Reset database
docker exec littleshop rm /app/data/littleshop-production.db
docker-compose restart

Permission Issues

# Fix volume permissions
docker exec -u root littleshop chown -R $APP_UID:$APP_UID /app/data /app/logs /app/uploads

Updates

To update the application:

1. Pull latest code

git pull

2. Rebuild and deploy

./docker-deploy-hostinger.sh

The script handles:

• Building new image
• Backing up data (recommended to do manually)
• Deploying new version
• Health check verification

Security Notes

1. Credentials: All sensitive credentials are in .env file
2. Network: Container bound to localhost only by default
3. Updates: Regularly update base images for security patches
4. Logs: Rotate logs to prevent disk space issues

Support

• Application logs: /opt/docker/littleshop/logs/
• Docker logs: docker logs littleshop
• Container shell: docker exec -it littleshop /bin/bash

Admin Access

• URL: http://localhost:5100/Admin
• Username: admin
• Password: admin

Remember to change the admin password after first login!