Installation Guide

Table of Contents

1. Windows Executable (.exe)
2. Production — Docker Compose (Recommended)
3. All-in-One — Single Docker Command (Testing only)
4. Standard Installation — PHP + MariaDB

Windows Executable (.exe)

⚠️ Not recommended for production. This option is designed for quick testing on Windows.

Steps

1. Download the file:

Download the Windows executable from the Releases page.

2. Installation:

Execute the downloaded .exe file. The application will be installed on your computer.

Option 1: Production — Docker Compose (Recommended)

Uses pre-built images from GitHub Container Registry. No source code or build tools required — just Docker and a .env file.

Prerequisites

• Docker >= 24
• Docker Compose >= 2.20

Steps

1. Download the Docker Compose file and environment template:

mkdir freeamir && cd freeamir
curl -O https://raw.githubusercontent.com/Jooyeshgar/FreeAmir/main/docker/production/docker-compose.prebuilt.yml
curl -O https://raw.githubusercontent.com/Jooyeshgar/FreeAmir/main/docker/production/.env.example
cp docker-compose.prebuilt.yml docker-compose.yml
cp .env.example .env

2. Edit .env and set your passwords and URL:

3. Pull images and start the containers:

docker compose up -d

4. Check startup logs:

docker compose logs -f php-fpm

Access the application at the APP_URL you configured (default: http://localhost).

💡 (Optional) Seed demo data after the containers are running:

docker compose exec php-fpm php artisan db:seed --class DemoSeeder

5. (Optional) Start phpMyAdmin for database management:

docker compose --profile tools up -d

Access phpMyAdmin at http://localhost:8080.

6. Stop the containers:

docker compose down

Option 2: All-in-One — Single Docker Command (Testing only)

⚠️ Not recommended for production. This image bundles PHP-FPM, Nginx, and MariaDB in a single container for quick evaluation. Data is lost when the container is removed unless a volume is mounted.

Prerequisites

• Docker >= 24

Steps

Pull and run:

docker run -d --name freeamir -p 80:80 -v freeamir-data:/var/lib/mysql ghcr.io/jooyeshgar/freeamir-all-in-one:latest

Access the application at http://localhost once startup completes.

💡 (Optional) Seed demo data after startup:

docker exec freeamir php artisan db:seed --class DemoSeeder

💡 To customise the URL or database credentials, pass environment variables:

docker run -d --name freeamir -p 80:80 \
  -e APP_URL=http://your-domain.com \
  -e DB_PASSWORD=secret \
  -v freeamir-data:/var/lib/mysql \
  ghcr.io/jooyeshgar/freeamir-all-in-one:latest

Check startup progress:

docker logs -f freeamir

Stop and remove:

docker stop freeamir && docker rm freeamir

Option 3: Standard Installation — PHP + MariaDB

Install directly on your server or workstation with PHP, Composer, Node.js, and MariaDB.

Prerequisites

• PHP >= 8.2 with extensions: pdo_mysql, gd, intl, zip, bcmath, mbstring, xml, opcache
• Composer
• MariaDB >= 10.6 (or MySQL >= 8.0)
• Node.js >= 18.0.0

Steps

1. Clone the repository:

git clone https://github.com/Jooyeshgar/FreeAmir.git
cd FreeAmir

2. Install PHP dependencies:

composer install --no-dev --optimize-autoloader

3. Configure environment:

cp .env.example .env

Edit .env and set DB_HOST, DB_DATABASE, DB_USERNAME, DB_PASSWORD, and APP_URL to match your environment.

4. Generate application key:

php artisan key:generate

5. Run database migrations:

php artisan migrate

6. Seed the database:

php artisan db:seed

Optional — seed with demo data:

php artisan db:seed --class DemoSeeder

7. Optimize application caches:

php artisan optimize

8. Installing and building frontend packages:

npm install
npm run build

9. Configure your web server to serve the public/ directory and point the document root there. For a quick local test:

php artisan serve

Access the application at http://localhost:8000.

Default Login

After seeding, all users share the password password. Available accounts:

Database Migration from Older Version

See Database Migration Guide for migrating from the older SQLite-based version.