EverShelf/docs/wiki/Installation.md

📦 Installation

EverShelf runs on any server with PHP 8.0+ and SQLite. Docker is the recommended approach for the fastest setup.

---

Prerequisites

Requirement	Minimum	Notes
PHP	8.0+	Extensions: pdo_sqlite, curl, mbstring, json
Web server	Apache 2.4+ or Nginx	Apache .htaccess included
SQLite	3.x	Bundled with PHP on most distros
HTTPS	Recommended	Required for camera access on mobile browsers
RAM	256 MB	512 MB+ recommended if using AI features

---

Option A: Docker (recommended)

The fastest way to get started.

# 1. Clone the repository
git clone https://github.com/dadaloop82/EverShelf.git
cd EverShelf

# 2. Create your configuration
cp .env.example .env
nano .env          # set GEMINI_API_KEY and other options

# 3. Start
docker compose up -d

# 4. Open in browser
# → http://localhost:8080

The Docker image:

• Uses PHP-Apache on Debian Bookworm slim
• Auto-creates the data/ directory with correct permissions
• Exposes port 8080 by default (configurable in docker-compose.yml)
• Persists data in a named Docker volume

Changing the port

Edit docker-compose.yml:

ports:
  - "8080:80"   # change 8080 to your desired host port

Using HTTPS with Docker

Add a reverse proxy (e.g. Traefik, Caddy, or Nginx Proxy Manager) in front of the container for automatic TLS.

---

Option B: Manual (Apache)

# 1. Clone into your web root
git clone https://github.com/dadaloop82/EverShelf.git /var/www/html/dispensa
cd /var/www/html/dispensa

# 2. Create configuration
cp .env.example .env
nano .env

# 3. Set permissions on the data directory
chmod 755 data/
chown -R www-data:www-data data/

Make sure mod_rewrite is enabled:

sudo a2enmod rewrite
sudo systemctl restart apache2

Apache virtual host (or add to .htaccess which is already included):

<VirtualHost *:443>
    ServerName evershelf.local
    DocumentRoot /var/www/html/dispensa

    <Directory /var/www/html/dispensa>
        AllowOverride All
        Require all granted
    </Directory>

    # Hide sensitive paths
    <LocationMatch "^/(data|\.env|backup\.sh)">
        Require all denied
    </LocationMatch>

    SSLEngine on
    SSLCertificateFile    /etc/ssl/certs/evershelf.crt
    SSLCertificateKeyFile /etc/ssl/private/evershelf.key
</VirtualHost>

---

Option C: Manual (Nginx)

server {
    listen 443 ssl;
    server_name evershelf.local;
    root /var/www/html/dispensa;
    index index.html;

    ssl_certificate     /etc/ssl/certs/evershelf.crt;
    ssl_certificate_key /etc/ssl/private/evershelf.key;

    location /api/ {
        try_files $uri $uri/ =404;
        location ~ \.php$ {
            fastcgi_pass unix:/run/php/php8.2-fpm.sock;
            fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
            include fastcgi_params;
        }
    }

    # Block sensitive files
    location ~ /\.env        { deny all; }
    location ~ /data/        { deny all; }
    location ~ /backup\.sh   { deny all; }

    location / {
        try_files $uri $uri/ /index.html;
    }
}

---

HTTPS Setup

Camera and microphone access (barcode scanning, voice) require HTTPS on all modern mobile browsers.

Self-signed certificate (local network)

openssl req -x509 -nodes -days 3650 -newkey rsa:2048 \
  -keyout /etc/ssl/private/evershelf.key \
  -out /etc/ssl/certs/evershelf.crt \
  -subj "/CN=evershelf.local" \
  -addext "subjectAltName=IP:192.168.1.100,DNS:evershelf.local"

Android will show a certificate warning — tap "Advanced → Proceed" once. The kiosk app accepts self-signed certificates automatically.

Let's Encrypt (public server)

sudo apt install certbot python3-certbot-apache
sudo certbot --apache -d evershelf.yourdomain.com

Caddy (automatic TLS)

evershelf.yourdomain.com {
    root * /var/www/html/dispensa
    php_fastcgi unix//run/php/php8.2-fpm.sock
    file_server
    respond /data/* 403
    respond /.env 403
}

---

Cron Job (optional)

For smart shopping predictions to stay up to date:

# Edit crontab
crontab -e

# Add (runs every 5 minutes)
*/5 * * * * php /var/www/html/dispensa/api/cron_smart_shopping.php >> /var/www/html/dispensa/data/cron.log 2>&1

---

Backup (optional)

# Edit crontab
crontab -e

# Daily backup at 3 AM
0 3 * * * /var/www/html/dispensa/backup.sh

The backup.sh script copies data/evershelf.db to data/backups/ with a timestamp.

---

Updating

cd /var/www/html/dispensa
git pull origin main
# Database migrations run automatically on next page load

With Docker:

docker compose pull
docker compose up -d

---

Post-installation

Once the app is running, open it in your browser and:

1. Go to Settings (⚙️ icon in the header)
2. Enter your Gemini API key (get one free at aistudio.google.com)
3. Optionally configure Bring!, TTS, and scale settings
4. Add your first product via the ➕ button or barcode scan

See Configuration for the full list of settings.