Installation

CyanFox Base Installation Guide

This guide will walk you through the process of setting up CyanFox Base with PHP 8.2, NodeJS, MariaDB, and a webserver (Apache or Nginx) on a Linux server.

Prerequisites

Ensure your system is up to date and has the required packages:

sudo apt update
sudo apt upgrade -y

Install Required Packages

Install Basic Utilities and Add PHP Repository

sudo apt install ca-certificates apt-transport-https lsb-release gnupg curl nano unzip git cron wget -y
sudo apt install software-properties-common -y
sudo add-apt-repository ppa:ondrej/php
sudo apt update

Install NodeJS

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash

# Restart Shell
bash

nvm install 22.3.0

Install PHP 8.2 and Extensions

sudo apt install php8.2 php8.2-cli php8.2-common php8.2-curl php8.2-gd php8.2-intl php8.2-mbstring php8.2-mysql php8.2-opcache php8.2-readline php8.2-xml php8.2-xsl php8.2-zip php8.2-bz2 -y

Install Composer

Composer is a dependency manager for PHP, which we need to install the necessary libraries for CyanFox Base.

curl -sS https://getcomposer.org/installer | sudo php -- --install-dir=/usr/local/bin --filename=composer

Install and Configure Web Server

You can choose between Apache and Nginx as your web server. Follow the instructions for the one you prefer.

Apache

sudo apt install apache2 libapache2-mod-php8.2 -y

Nginx

sudo apt install nginx -y

Install MariaDB

MariaDB is the database server we will use to store CyanFox Base's data.

sudo apt install mariadb-server mariadb-client -y

Clone the CyanFox Base Repository

Navigate to your web server's root directory and clone the CyanFox Base repository:

cd /var/www
git clone https://github.com/CyanFox-Projects/CyanFox-Base

Configure Web Server

Apache Configuration

Create a new virtual host configuration for CyanFox Base. Replace <domain> with your actual domain name.

sudo nano /etc/apache2/sites-available/cyanfox.conf

Add the following configuration:

<VirtualHost *:80>
  ServerName <domain>
  DocumentRoot "/var/www/CyanFox-Base/public"
  
  AllowEncodedSlashes On
  
  php_value upload_max_filesize 100M
  php_value post_max_size 100M
  
  <Directory "/var/www/CyanFox-Base/public">
    AllowOverride all
    Require all granted
  </Directory>
</VirtualHost>

Enable the new site and restart Apache:

a2dissite 000-default.conf
sudo a2ensite cyanfox.conf
sudo systemctl restart apache2

Nginx Configuration

Create a new server block configuration for CyanFox Base. Replace <domain> with your actual domain name.

sudo rm /etc/nginx/sites-enabled/default
sudo nano /etc/nginx/sites-available/cyanfox

Add the following configuration:

server {
    listen 80;
    server_name <domain>;

    root /var/www/CyanFox-Base/public;
    index index.php index.html index.htm;

    location / {
        try_files $uri $uri/ /index.php?$query_string;
    }

    location ~ \.php$ {
        include snippets/fastcgi-php.conf;
        fastcgi_pass unix:/var/run/php/php8.2-fpm.sock;
        fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
        include fastcgi_params;
    }

    location ~ /\.ht {
        deny all;
    }

    client_max_body_size 100M;
}

Enable the new site and restart Nginx:

sudo ln -s /etc/nginx/sites-available/cyanfox /etc/nginx/sites-enabled/
sudo systemctl restart nginx

Set Up File Permissions

Navigate to your CyanFox Base directory and set the appropriate permissions:

cd /var/www/CyanFox-Base
sudo chmod -R 755 storage/* bootstrap/cache/
sudo chown -R www-data:www-data .

Configure MariaDB

Log in to MariaDB and create the necessary database and user:

sudo mysql -u root -p

Run the following SQL commands, replacing password with a secure password:

CREATE USER 'cyanfox'@'127.0.0.1' IDENTIFIED BY 'password';
CREATE DATABASE cyanfox;
GRANT ALL PRIVILEGES ON cyanfox.* TO 'cyanfox'@'127.0.0.1' WITH GRANT OPTION;
EXIT;

Configure Environment Variables

Copy the example environment file and edit it:

cp .env.example .env
nano .env

Update the following database settings in the .env file:

DB_CONNECTION=mysql
DB_HOST=127.0.0.1
DB_PORT=3306
DB_DATABASE=cyanfox
DB_USERNAME=cyanfox
DB_PASSWORD=password

Install Dependencies and Migrate Database

Install Composer dependencies and set up the application:

composer update --no-dev --optimize-autoloader
php artisan key:generate --force
php artisan migrate

Install NPM packages and build assets

npm i
npm run build

Setup icons

php artisan tallstackui:setup-icons --force

Set Up Cron Job

Set up a cron job to run the Laravel scheduler:

sudo crontab -e

Add the following line to the crontab:

* * * * * php /var/www/CyanFox-Base/artisan schedule:run >> /dev/null 2>&1

Conclusion

Your CyanFox Base application should now be up and running. You can access it by navigating to your domain in a web browser. Make sure to replace all placeholder values with your actual configurations.