Installation Guide - Zoo Arcadia

This comprehensive guide covers everything you need to install and configure Zoo Arcadia on your system.

System Requirements

Required Software

PHP

Version 7.4 or higher (8.x recommended)

Composer

Latest stable version for dependency management

Node.js

Version 14+ with npm included

Database

MySQL 8.0+ or MariaDB 11.4+

Optional Software

Docker Desktop - For containerized deployment (recommended)
Git - For version control and cloning the repository

Installation Methods

Docker Installation
Local Installation

Docker provides a consistent, isolated environment for Zoo Arcadia.

Prerequisites

Install Docker Desktop

Download and install Docker Desktop for your operating system:

Verify Docker installation

docker --version
docker-compose --version

Setup Process

Clone the repository

git clone https://github.com/dumitrusf/zoo-Arcadia.git
cd zoo-ARCADIA

Configure environment

Run the Docker configuration script:

.\switch-to-docker.bat

This creates/updates your .env file with Docker-specific settings:

DB_HOST=db
DB_NAME=zoo_arcadia
DB_USER=zoo_user
DB_PASS=zoo_password

Review Docker Compose configuration

The docker-compose.yml defines three services:Web Service (PHP + Apache)

Exposes port 8080
Mounts source directories for development
Automatically installs dependencies

Database Service (MariaDB 11.4)

Exposes port 3306
Persistent volume for data storage
Auto-initializes with SQL scripts from database/ directory

Build and start containers

docker-compose up -d --build

The --build flag ensures all dependencies are installed and assets are compiled. This may take a few minutes on first run.

Verify containers are running

docker-compose ps

You should see:

zoo-arcadia-web - Status: Up
zoo-arcadia-db - Status: Up

Check application logs

docker-compose logs -f web

Press Ctrl+C to exit log view.

Docker Container Management

docker-compose ps

Database Management (Docker)

docker-compose down -v && docker-compose up -d

Updating Code in Docker

When you modify composer.json, package.json, or source files:

docker-compose up -d --build

Docker volumes automatically sync changes to PHP files, so you don’t need to rebuild for simple code changes. Only rebuild when dependencies change.

Install Zoo Arcadia directly on your local machine.

Prerequisites Installation

Install PHP

Windows:

Download from php.net
Or use XAMPP/WAMP which includes PHP, MySQL, and Apache

macOS:

brew install [email protected]

Linux (Ubuntu/Debian):

sudo apt update
sudo apt install php php-mysql php-mbstring php-xml php-curl

Verify installation:

php --version

Install Composer

Download from getcomposer.orgVerify installation:

composer --version

Install Node.js and npm

Download from nodejs.org (LTS version recommended)Verify installation:

node --version
npm --version

Install MySQL/MariaDB

Windows:

MariaDB Download
Or use XAMPP/WAMP

macOS:

brew install mariadb
brew services start mariadb

Linux:

sudo apt install mariadb-server
sudo systemctl start mariadb

Verify installation:

mysql --version

Application Setup

Clone the repository

git clone https://github.com/dumitrusf/zoo-Arcadia.git
cd zoo-ARCADIA

Install PHP dependencies

composer install

This installs:

intervention/image - Image manipulation
phpmailer/phpmailer - Email functionality
cloudinary/cloudinary_php - Cloud image storage
vlucas/phpdotenv - Environment variable management

Install Node.js dependencies

npm install

This installs:

Bootstrap 5.3.7
jQuery 3.7.1
DataTables
Gulp build tools

Configure environment variables

Run the local configuration script:

.\switch-to-local.bat

Or manually create .env from .env.example:

cp .env.example .env

Edit .env with your local settings:

# Database Configuration
DB_HOST=localhost
DB_NAME=zoo_arcadia
DB_USER=root
DB_PASS=root

# Email Configuration (SMTP)
SMTP_HOST=smtp.gmail.com
SMTP_PORT=587
SMTP_SECURE=tls
SMTP_USER[email protected]
SMTP_PASS=your-app-password
SMTP_FROM_EMAIL[email protected]
SMTP_FROM_NAME=Arcadia Zoo

# Zoo contact email
ZOO_EMAIL[email protected]

# Environment
APP_ENV=development

# Cloudinary (Optional)
CLOUDINARY_CLOUD_NAME=your-cloud-name
CLOUDINARY_API_KEY=your-api-key
CLOUDINARY_API_SECRET=your-api-secret

Deploy the database

Windows:

.\deploy_database.bat

Linux/macOS:

chmod +x deploy.sh
./deploy.sh

The deployment script recreates the entire database. All existing data will be lost.

The script executes SQL files in order:

01_init.sql - Database initialization
02_tables.sql - Table creation
03_constraints.sql - Foreign keys and constraints
04_indexes.sql - Performance indexes (if exists)
05_procedures.sql - Stored procedures (if exists)
06_seed_data.sql - Initial data (roles, users, animals, etc.)
07_cleanup.sql - Cleanup unused tables (if exists)

Compile assets

Build CSS from SCSS and minify JavaScript:

npx gulp buildCss && npx gulp buildJs

Assets are compiled to public/build/:

public/build/css/ - Compiled CSS files
public/build/js/ - Compiled and minified JS files

Start the development server

Using PHP’s built-in server:

php -S localhost:3001 -t public public/index.php

Or use Apache/Nginx with document root pointing to public/

Development Workflow

For active development with automatic recompilation:

npx gulp

This starts:

SCSS/JS file watchers
BrowserSync for live reload
Automatic compilation on file changes

BrowserSync proxies http://localhost:3001 and opens a new browser window with live reload enabled.

Environment Configuration

Database Configuration

The .env file controls all database connections:

DB_HOST=db
DB_NAME=zoo_arcadia
DB_USER=zoo_user
DB_PASS=zoo_password

Email Configuration

Configure SMTP for contact form and notifications:

SMTP_HOST=smtp.gmail.com
SMTP_PORT=587
SMTP_SECURE=tls
SMTP_USER[email protected]
SMTP_PASS=your-app-password
SMTP_FROM_EMAIL[email protected]
SMTP_FROM_NAME=Arcadia Zoo
ZOO_EMAIL[email protected]

For Gmail, you need to create an App Password instead of using your regular password.

Cloudinary Configuration (Optional)

For cloud-based image storage:

CLOUDINARY_CLOUD_NAME=your-cloud-name
CLOUDINARY_API_KEY=your-api-key
CLOUDINARY_API_SECRET=your-api-secret

Database Setup

Database Schema

Zoo Arcadia uses a modular SQL structure:

01_init.sql - Creates database and sets character encoding
02_tables.sql - Defines all tables (users, animals, habitats, services, etc.)
03_constraints.sql - Foreign key relationships and constraints
04_indexes.sql - Performance optimization indexes
05_procedures.sql - Stored procedures for complex operations
06_seed_data.sql - Initial data for development/testing
07_cleanup.sql - Removes deprecated tables

Manual Database Deployment

If automated scripts don’t work, execute SQL files manually:

mysql -u root -p < database/01_init.sql
mysql -u root -p zoo_arcadia < database/02_tables.sql
mysql -u root -p zoo_arcadia < database/03_constraints.sql
mysql -u root -p zoo_arcadia < database/06_seed_data.sql

Seed Data

The 06_seed_data.sql file includes:

Roles: Admin, Veterinary, Employee, Accountant
Employees: Sample employee records
Users: Login credentials for each role
Animals: Sample zoo animals with details
Habitats: Savanna, Jungle, Marsh environments
Services: Restaurant, guided tours, train ride

Review database/06_seed_data.sql for default credentials before deploying to production.

Asset Compilation

Build Commands

npx gulp buildCss && npx gulp buildJs

Asset Pipeline

The Gulp configuration (gulpfile.js) handles: CSS Processing:

Compiles src/scss/app.scss → public/build/css/app.css
Compiles src/scss/bo-sidebar-only.scss for back-office
Copies vendor CSS (Bootstrap, DataTables, Normalize.css)

JavaScript Processing:

Minifies src/js/app.js with Terser
Compiles individual filter scripts:
- animals-filter.js
- habitat-filter.js
- rating-testimony.js
Generates source maps for debugging
Copies vendor JS (jQuery, Bootstrap, DataTables)

Development Features:

BrowserSync for live reload
File watching for automatic recompilation
Proxy to http://localhost:3001

Verification Steps

Check PHP configuration

php --ini

Verify extensions are loaded: mysqli, pdo_mysql, mbstring, curl, gd

Test database connection

mysql -u root -p -e "SHOW DATABASES;"

Verify zoo_arcadia database exists

Verify assets compiled

Check that public/build/ contains:

css/app.css
css/bo-sidebar-only.css
css/bootstrap.min.css
js/app.js
js/jquery.min.js

Access the application

Docker: http://localhost:8080Local: http://localhost:3001You should see the Zoo Arcadia homepage.

Test back-office access

Navigate to /home/pages/login-personnel and attempt to log in with credentials from 06_seed_data.sql.

Troubleshooting

SSL Certificate Error (Windows)

If composer install fails with curl error 60: SSL certificate problem:

Download cacert.pem

Download from curl.se/ca/cacert.pemSave to a permanent location, e.g., C:\php\cacert.pem

Locate php.ini

php --ini

Note the “Loaded Configuration File” path

Update php.ini

Add or update these lines:

[curl]
curl.cainfo = "C:\php\cacert.pem"

[openssl]
openssl.cafile = "C:\php\cacert.pem"

Restart services

Close and reopen your terminal
Restart Apache if using XAMPP/WAMP
Retry composer install

Port Conflicts

Port 8080 (Docker) already in use:

# Edit docker-compose.yml
web:
  ports:
    - "8081:80"  # Change external port

Port 3001 (Local) already in use:

php -S localhost:3002 -t public public/index.php

Database Connection Issues

Access denied for user

Verify credentials in .env match your MySQL/MariaDB setup:

mysql -u root -p

If you can’t connect, reset the root password or create a new user.

Database does not exist

Run the database deployment script:

.\deploy_database.bat  # Windows
./deploy.sh            # Linux/macOS

Can't connect to MySQL server

Ensure MySQL/MariaDB service is running:

# Windows (XAMPP)
# Start via XAMPP Control Panel

# macOS
brew services start mariadb

# Linux
sudo systemctl start mariadb

Asset Compilation Errors

gulp: command not found

Install Gulp globally or use npx:

npm install -g gulp-cli
# OR
npx gulp

Node Sass binding error

Rebuild node-sass:

npm rebuild node-sass

Permission denied errors

Windows: Run terminal as AdministratormacOS/Linux:

sudo npm install -g gulp-cli

Docker-Specific Issues

Container won't start

Check logs for errors:

docker-compose logs web
docker-compose logs db

Database not initializing

Ensure SQL files are being mounted:

docker exec -it zoo-arcadia-db ls /docker-entrypoint-initdb.d

If empty, rebuild:

docker-compose down -v
docker-compose up -d --build

Changes not reflecting in browser

For PHP changes: Refresh browser (changes are mounted in real-time)For dependencies: Rebuild container:

docker-compose up -d --build

Project Structure

zoo-ARCADIA/
├── App/                    # Domain-based architecture (MVC per domain)
│   ├── Animals/
│   ├── Auth/
│   ├── Habitats/
│   └── Services/
├── public/                 # Front controller and compiled assets
│   ├── index.php           # Application entry point
│   └── build/              # Compiled CSS/JS
├── src/                    # Source SCSS and JavaScript
│   ├── scss/
│   └── js/
├── database/               # Versioned SQL scripts
│   ├── 01_init.sql
│   ├── 02_tables.sql
│   ├── 03_constraints.sql
│   └── 06_seed_data.sql
├── includes/               # Shared helpers and layouts
│   ├── csrf.php
│   ├── functions.php
│   └── layouts/
├── .env                    # Environment configuration
├── .env.example            # Environment template
├── composer.json           # PHP dependencies
├── package.json            # Node.js dependencies
├── docker-compose.yml      # Docker configuration
├── gulpfile.js            # Asset build configuration
└── README.md              # Project documentation

Next Steps

After successful installation:

Explore the codebase architecture in App/
Review the front controller pattern in public/index.php
Check routing configuration in App/router.php
Review security implementations (CSRF tokens, input validation)
Test all user roles (Admin, Veterinary, Employee)

Additional Resources

Project Documentation: docs/DOSSIER_PROJET_ZOO_ARCADIA.md
Live Demo: https://zoo-arcadia-production.up.railway.app
GitHub Repository: https://github.com/dumitrusf/zoo-Arcadia

Get Started

Architecture

Core Features

User Guides

Development

​System Requirements

​Required Software

PHP

Composer

Node.js

Database

​Optional Software

​Installation Methods

​Prerequisites

​Setup Process

​Docker Container Management

​Database Management (Docker)

​Updating Code in Docker

​Prerequisites Installation

​Application Setup

​Development Workflow

​Environment Configuration

​Database Configuration

​Email Configuration

​Cloudinary Configuration (Optional)

​Database Setup

​Database Schema

​Manual Database Deployment

​Seed Data

​Asset Compilation

​Build Commands

​Asset Pipeline

​Verification Steps

​Troubleshooting

​SSL Certificate Error (Windows)

​Port Conflicts

​Database Connection Issues

​Asset Compilation Errors

​Docker-Specific Issues

​Project Structure

​Next Steps

​Additional Resources

Build docs developers (and LLMs) love

System Requirements

Required Software

Optional Software

Installation Methods

Prerequisites

Setup Process

Docker Container Management

Database Management (Docker)

Updating Code in Docker

Prerequisites Installation

Application Setup

Development Workflow

Environment Configuration

Database Configuration

Email Configuration

Cloudinary Configuration (Optional)

Database Setup

Database Schema

Manual Database Deployment

Seed Data

Asset Compilation

Build Commands

Asset Pipeline

Verification Steps

Troubleshooting

SSL Certificate Error (Windows)

Port Conflicts

Database Connection Issues

Asset Compilation Errors

Docker-Specific Issues

Project Structure

Next Steps

Additional Resources