Install ShelfSpot at home

This guide provides step-by-step instructions for installing ShelfSpot using two different methods: Classic Installation (minimal setup) and Complete Installation (full stack with database).

Prerequisites

Before starting, make sure you have the following:

• Docker Engine (version 20.10 or higher)
• Docker Compose (v1.29 or higher, or Docker Compose v2)
• Git (to clone the repository)
• Linux/macOS/Windows with Docker support
• At least 2 GB of RAM and 5 GB of disk space

Installing Docker

If Docker is not installed:

• Linux: Follow the official Docker installation guide
• macOS: Download Docker Desktop for Mac
• Windows: Download Docker Desktop for Windows

Verify your installation:

docker --version
docker-compose --version

Installation methods

Choose the method that best suits your needs:

Method 1: Classic Installation (Recommended for development)

Classic installation offers minimal setup that builds and runs the ShelfSpot application without an integrated database. This method is ideal for:

• Development and testing
• Quick demos
• If you already have a database server

Steps:

1. Navigate to the classic installation folder:

   cd install/classic_install

2. Make the build script executable:

   chmod +x build.sh

3. Run the build script:

   ./build.sh

   This script will:

   • Build Docker images for frontend and backend
   • Verify images are created successfully

4. Configure environment variables: Make sure you have a .env file in the backend folder with your database configuration:

   # Example .env file
   DATABASE_URL="mysql://user:password@host:3306/shelfspot"
   JWT_SECRET="your-secret-key"

5. Start services:

   docker-compose up -d

6. Verify installation:

   docker-compose ps

   Check that services are running:

   • Backend: Available at http://localhost:3001
   • Frontend: Available at http://localhost:3000

7. Check logs (if needed):

   docker-compose logs -f

Included services:

• Backend API (NestJS) on port 3001
• Frontend (Next.js) on port 3000

Method 2: Complete Installation (Production-ready)

Complete installation offers full-stack deployment including MariaDB database and all necessary services. This method is ideal for:

• Production deployments
• Complete test environment
• If you want everything preconfigured

Steps:

1. Navigate to the complete installation folder:

   cd install/complete_install

2. Make the build script executable:

   chmod +x build.sh

3. Run the build script:

   ./build.sh

   This script prepares all components necessary for complete deployment.

4. Configure environment variables (optional): Create a .env file to override default settings:

   # Optional .env file for complete installation
   DB_ROOT_PASSWORD=root-password
   DB_NAME=shelfspot
   DB_USER=shelfspot_user
   DB_PASSWORD=user-password
   DB_PORT=3306

5. Start the complete stack:

   docker-compose -f docker-compose.full.yml up -d

6. Wait for database initialization: The database needs time to initialize. Monitor the process:

   docker-compose -f docker-compose.full.yml logs -f database

   Wait to see “ready for connections” in the logs.

7. Run database migrations (if needed):

   docker-compose -f docker-compose.full.yml exec backend npm run prisma:migrate:deploy

8. Verify installation:

   docker-compose -f docker-compose.full.yml ps

   All services should be healthy:

   • Database (MariaDB) on port 3306
   • Backend API on port 3001
   • Frontend on port 3000

Included services:

• MariaDB Database on port 3306
• Backend API (NestJS) on port 3001
• Frontend (Next.js) on port 3000
• Database initialization scripts (in database/init/)

After installation

Accessing the application

Once installation is complete, you can access:

• Frontend: http://localhost:3000
• Backend API: http://localhost:3001
• API Documentation: http://localhost:3001/api (Swagger)

Default credentials

If using complete installation with default settings:

• Database:
  • Host: localhost:3306
  • Database: shelfspot
  • User: shelfspot_user
  • Password: ShelfSpot2024!

Checking service status

Both installation methods include verifications:

# Check all services
docker-compose ps

# Check logs for a specific service
docker-compose logs backend
docker-compose logs frontend

# For complete installation
docker-compose -f docker-compose.full.yml logs database

Troubleshooting

Common issues

1. Port conflicts:

   # Check what's using ports
   sudo netstat -tulpn | grep :3000
   sudo netstat -tulpn | grep :3001
   sudo netstat -tulpn | grep :3306

2. Docker permission issues:

   # Add user to docker group
   sudo usermod -aG docker $USER
   # Then log out and log back in

3. Database connection issues:

   • Check that the database container is healthy
   • Check environment variables in .env files
   • Check network connectivity between containers

4. Build failures:

   # Clean Docker cache and rebuild
   docker system prune -a
   docker-compose down -v
   # Then run the build script again

Getting help

In case of issues:

1. Check logs: docker-compose logs <service-name>
2. Verify all containers are running: docker-compose ps
3. Check documentation in documentation/ folder
4. Check specific READMEs in backend/ and frontend/

Stopping and cleanup

Stopping services:

# Classic installation
docker-compose down

# Complete installation
docker-compose -f docker-compose.full.yml down

Complete cleanup (removes data):

# Remove containers, networks, and volumes
docker-compose down -v

# For complete installation
docker-compose -f docker-compose.full.yml down -v

Development notes

• For development, classic installation is recommended as it’s faster to start/stop
• Use complete installation to test database-specific features
• Both methods support hot-reloading during development
• Environment variables can be customized in respective .env files

For more information, check the documentation on the project homepage.