Merchant & operations

Install Agovena

Install Agovena on Ubuntu or Debian, then configure a web server, queue worker and cron.

On this page

Check the supported environments on the Server requirements page before choosing a path.

Do not run Nginx and Apache on the same ports. A native installation needs one of them as its web server.

1. Prepare the server

Native Linux

Use the tab for your operating system. The package names below install the required PHP extensions, MariaDB, Composer, Git, archive tools and cron.

bash

sudo apt update
sudo apt install -y ca-certificates curl git tar unzip composer cron mariadb-server mariadb-client \
  php-cli php-fpm php-mysql php-mbstring php-xml php-curl php-zip php-intl php-bcmath
sudo systemctl enable --now mariadb cron

bash

sudo apt-get update
sudo apt-get install -y ca-certificates curl git tar unzip composer cron mariadb-server mariadb-client \
  php-cli php-fpm php-mysql php-mbstring php-xml php-curl php-zip php-intl php-bcmath
sudo systemctl enable --now mariadb cron

Check the PHP version before continuing. It must be PHP 8.3 or PHP 8.4:

bash

php -v
php -m | grep -E 'bcmath|curl|intl|mbstring|mysql|xml|zip'

Find the PHP-FPM service and start the service for the PHP version you installed:

bash

systemctl list-unit-files 'php*-fpm.service'
sudo systemctl enable --now php8.3-fpm

If your server uses PHP 8.4, replace php8.3-fpm with php8.4-fpm. Keep the PHP CLI and PHP-FPM versions the same.

Create the database

Create a separate MariaDB database and user. Do not use the MariaDB root account in .env:

bash

sudo mariadb

sql

CREATE DATABASE agovena CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
CREATE USER 'agovena'@'localhost' IDENTIFIED BY 'CHANGE_ME';
GRANT ALL PRIVILEGES ON agovena.* TO 'agovena'@'localhost';
FLUSH PRIVILEGES;
EXIT;

Replace CHANGE_ME with a password stored in your password manager. Do not put it in Git, screenshots or support requests.

2. Get Agovena

Create the application directory:

bash

sudo mkdir -p /var/www/agovena
sudo chown "$USER":"$USER" /var/www/agovena

Latest release

The following command finds the newest published Agovena archive through GitHub and downloads it. It does not download the moving main branch:

bash

cd /var/www
rm -rf /tmp/agovena-release
mkdir -p /tmp/agovena-release
RELEASE_URL="$(curl -fsSL https://api.github.com/repos/milovd/Agovena/releases/latest 2>/dev/null | sed -n 's/.*"browser_download_url": "\(https:[^"]*agovena-[^"]*\.tar\.gz\)".*/\1/p' | head -n 1 || true)"
if [ -z "$RELEASE_URL" ]; then
  printf '%s\n' 'No matching published release archive found. Use the source checkout instead.'
  exit 1
fi
curl -fL "$RELEASE_URL" -o /tmp/agovena-latest.tar.gz
tar -xzf /tmp/agovena-latest.tar.gz -C /tmp/agovena-release
sudo cp -a /tmp/agovena-release/agovena-*/. /var/www/agovena/

If the command reports that no archive was found, use the Source checkout below. When an archive is available, it already contains the matching Composer dependencies and built frontend assets.

Source checkout

Use a source checkout when you intentionally deploy the current main branch or build the release yourself:

bash

sudo git clone --depth 1 --branch main https://github.com/milovd/Agovena.git /var/www/agovena
sudo chown -R "$USER":www-data /var/www/agovena
cd /var/www/agovena
composer install --no-dev --optimize-autoloader
npm ci
npm run build

For a later source update, use git pull --ff-only origin main in this checkout. Do not use composer update; it can select different dependency versions.

3. Configure the environment

Create .env only on a new installation:

bash

cd /var/www/agovena
cp .env.example .env
php artisan key:generate

Edit .env and set the real values for your store:

env

APP_ENV=production
APP_DEBUG=false
APP_URL=https://store.example
DB_CONNECTION=mysql
DB_HOST=127.0.0.1
DB_PORT=3306
DB_DATABASE=agovena
DB_USERNAME=agovena
DB_PASSWORD=[REDACTED]
QUEUE_CONNECTION=database

Also configure the mail transport that your store will use. Keep .env outside version control. Never overwrite an existing .env or generate a new APP_KEY during an update or restore.

4. Set the file permissions

The web server, queue worker and scheduler need write access to storage/ and bootstrap/cache/. Keep the rest of the application owned by the deployment user:

bash

cd /var/www/agovena
DEPLOY_USER="${SUDO_USER:-$USER}"
sudo chown -R "$DEPLOY_USER":www-data /var/www/agovena
sudo chmod -R ug+rwX storage bootstrap/cache

Do not use chmod 777. Keep .env, storage/app/private and the application source out of the public document root.

5. Run the installer

Run the database migrations, create the public storage link and start the Agovena installer:

bash

cd /var/www/agovena
php artisan migrate --force
php artisan storage:link
php artisan agovena:install

The installer asks for the owner, store name, language, timezone, currency and theme. Its password prompt is hidden. You can also open /install after the web server is configured.

An installed store must not be installed a second time. Keep the installation marker in storage/app/agovena/.

6. Choose the web server

Set the document root to the public/ directory:

text

/var/www/agovena/public

Never point a web server at /var/www/agovena. Choose exactly one guide:

Choose the web server after Agovena is in /var/www/agovena and the application environment is configured. The web server is the final public entry point, not a replacement for the Agovena installer.

Choose a web server

Install and configure Nginx with PHP-FPM by following the Nginx guide. Set its root to /var/www/agovena/public, then reload Nginx and open the store URL.

Install Apache with PHP-FPM by following the Apache guide. Enable the required proxy and rewrite modules, set the virtual host root to /var/www/agovena/public, then reload Apache.

After the web server is working, set APP_URL to the same HTTPS address. Follow the HTTPS guide before collecting customer or administrator credentials.

7. Run the queue worker

Agovena uses a persistent queue worker for queued mail, webhooks, subscription work and provisioning. Install the supplied systemd unit:

bash

cd /var/www/agovena
sudo cp deploy/systemd/agovena-queue.service /etc/systemd/system/agovena-queue.service
sudo systemctl daemon-reload
sudo systemctl enable --now agovena-queue.service
sudo systemctl status agovena-queue.service

The unit runs:

bash

/usr/bin/php /var/www/agovena/artisan queue:work --sleep=1 --tries=3 --timeout=60 --backoff=5 --max-time=3600

If your PHP binary or application path is different, edit the unit before enabling it. Use either systemd or the supplied Supervisor configuration, not both for the same worker.

8. Add the scheduler cronjob

Open the crontab for the same runtime user as PHP-FPM and the queue worker:

bash

sudo -u www-data crontab -e

Add this line:

cron

* * * * * cd /var/www/agovena && /usr/bin/php artisan schedule:run >> /dev/null 2>&1

This single cronjob runs tasks that are due. It must stay in place after updates. Check it with:

bash

sudo -u www-data crontab -l
php artisan schedule:list
php artisan schedule:run

schedule:run executes due tasks. It is useful during setup, but it is not a read-only command.

9. Enable HTTPS

Point your DNS record to the server, open ports 80 and 443, then follow the HTTPS guide. Keep APP_URL on the HTTPS origin and test certificate renewal before opening the store.

10. Check the installation

Run the platform checks and inspect the real service state:

bash

cd /var/www/agovena
composer check-platform-reqs --no-dev
php artisan agovena:doctor
sudo systemctl is-active nginx
sudo systemctl is-active mariadb
sudo systemctl is-active agovena-queue.service

Open the public store URL and complete the installer if this is a fresh deployment. After installation, check a public image, a route that is not a physical file, email delivery, one queued job and the scheduler heartbeat in Admin.

11. After installation

Continue with:

Configure the store.
Add the first product.
Configure payments.
Set up backups.
Read updates and database migrations before replacing application files.