ColibriDocs

Appearance

Installation Guide ​

First of all, ColibriPlus is a Laravel powered application. It is's also Linux first environment.

You mostly need VPS/VDS server to run ColibriPlus, because it's a full-stack web app with node, php, mysql, redis, and other services.

Requirements ​

Please make sure you have the following requirements:

  • PHP 8.3+
  • MySQL 8.0+ or any relational database like PostgreSQL, SQLite, etc.
  • Node.js 22.x+
  • Redis 7.0+
  • Composer
  • NPM
  • Git (optional but highly recommended)
  • Apache/Nginx

PHP Extensions (Important 🔴) ​

Please make sure your server has already installed the following PHP extensions from Requirements file, before you start the installation.

Installation ​

  1. Once you download the colibriplus archive, you will see the following files:
bash
colibriplus/
├── Documentation
├── Source
├── Updates
  1. Inside the Source folder, you will see the all source code and files of ColibriPlus.

Upload all files from Source folder to your server. To the root directory of your domain where you want to install ColibriPlus.

FS Permissions ​

ColibriPlus requires some permissions to be set for the storage and public directories.

bash
# Go to the root directory of your ColibriPlus application
cd /path/to/your/colibriplus

# Set the correct permissions for the storage and public directories
sudo chown -R $USER:www-data .
chmod -R ug+rwx storage bootstrap/cache

Copy .env file ​

To get started, you have to copy .env.example file to .env and edit the file.

bash
cp .env.example .env

Install Dependencies ​

Now you have to install two types of dependencies, first is PHP dependencies and second is CSS/JS/Node.js dependencies.

Since you already have PHP installed with composer, you can just run the following command to install PHP dependencies:

bash
composer install

Once you see a success message from Composer installation, let's install Node.js dependencies.

bash
npm install

If everything is done right, all PHP and NodeJS dependencies will be installed successfully and we can move to the next step.

Base Configuration ​

Each ColibriPlus application has it's own unique configuration. Like project name, description, logo, etc. All configuration variables are stored in the .env file.

bash
APP_NAME=ColibriPlus
APP_DESCRIPTION="Here goes your project description"

# or development, staging, testing
APP_ENV=production

# or http://your-domain.com
APP_URL=https://your-domain.com

# or your timezone
APP_TIMEZONE=UTC

# or development, staging, testing
NODE_ENV=production

# or development, staging, testing
SANCTUM_STATEFUL_DOMAINS=your-domain.com,www.your-domain.com,localhost,127.0.0.1
ADMIN_EMAIL=admin@your-domain.com

# you can change it later when you add more languages for your project
ADMIN_LOCALE=en/ru

# you can use any random string here like UUID or other hash.
APP_API_KEY=your-api-key-here

# admin panel url prefix. You can change it later.
APP_ADMIN_PREFIX=admin
APP_LOCALE=en/ru # you can change it later when you add more languages for your project

Database Configuration ​

Now, we are ready to configure the DB for your application. Do the following steps:

  1. Open the .env file and edit the following variables:
bash
# or any other database you want to use
DB_CONNECTION=mysql

# or your database host
DB_HOST=127.0.0.1

# or your database port
DB_PORT=3306

# or your database name
DB_DATABASE=colibriplus

# replace with your database username
DB_USERNAME=username

# replace with your database password
DB_PASSWORD=password

The next step is to generate the app key and apply the migrations. Run the following command:

bash
php colibri key:generate
php colibri migrate --force
php colibri db:seed
php colibri livewire:publish --assets
php colibri storage:link

If the database does not exist yet, the CLI may prompt you to create it automatically. Confirm with Y and hit enter.

These commands will create the database tables and seed the database with the default data.

Building Frontend ​

If all previous steps are completed right, we must move to the next step - building frontend.

Since ColibriPlus frontend is built with VueJS and TailwindCSS, we use Vite for building frontend. So, you need to run the following command to build the frontend:

✋ But first, we need to create a file to store the build number. ​

Create the file storage/frontend/build.num and set the build number to 1.

bash
mkdir -p storage/frontend
echo 1 > storage/frontend/build.num
bash
npm run build

If everything runs correctly, all frontend assets will be built and stored in the public/dist directory.

Redis Setup ​

ColibriPlus uses Redis for caching and session management. So, you need to configure Redis for your application.

  1. Open the .env file and edit the following variables:
bash
REDIS_HOST=127.0.0.1 # or your Redis host
REDIS_PORT=6379 # or your Redis port
REDIS_PASSWORD=ENTER PASSWORD FOR REDIS IF YOU HAVE ONE

Redis will now be properly connected to your application and you can move to the next step.

HTTP Server ​

ColibriPlus allows you to use any HTTP server you want to use. But, we recommend you to use Nginx for production environment. And the documentation below is for Nginx.

Nginx configuration ​

WARNING

✋✋✋✋✋
Attention! At this stage, your nginx server must be running and listening on port 443. As we are using SSL, you must have a valid SSL certificate for your domain. You can use Let's Encrypt for free.

This guide does not cover the HTTP server setup, SSL certificate setup, or any other server tools. If you are not familiar with these tools, please consider using our installation service. You can contact me via My website.

You can find the Nginx configuration file example in docker/nginx/conf.d/nginx.conf file.

Please note that your Nginx root must root must point to the public directory of your application not the root directory itself.

You can add or change server block for your needs if you know what you are doing. But we provide the optimal configuration for you.

bash
server {
	listen 443 ssl;
	server_name your-domain.com www.your-domain.com;
	root /path/to/your/colibriplus/public;

	client_max_body_size 4G;

	# 2 hours timeout
	proxy_read_timeout 7200s;
    proxy_connect_timeout 7200s;
    proxy_send_timeout 7200s;
    send_timeout 7200s;
	
	add_header X-Frame-Options "SAMEORIGIN";
	add_header X-XSS-Protection "1; mode=block";
	add_header X-Content-Type-Options "nosniff";

	index index.html index.htm index.php;

	charset utf-8;

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

	# Laravel broadcast server for websockets. Reverb server.
	location /app {
        proxy_http_version 1.1;
        proxy_set_header Host $http_host;
        proxy_set_header Scheme $scheme;
        proxy_set_header SERVER_PORT $server_port;
        proxy_set_header REMOTE_ADDR $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "Upgrade";

        proxy_pass http://0.0.0.0:13000; # If your Reverb server will be running on 0.0.0.0:13000
    }

	location = /favicon.ico { access_log off; log_not_found off; }
	location = /robots.txt  { access_log off; log_not_found off; }

	error_page 404 /index.php;

	location ~ \.php$ {
		try_files $uri =404;
		fastcgi_split_path_info ^(.+\.php)(/.+)$;
		fastcgi_pass localhost:9000; # If your PHP-FPM server will be running on localhost:9000
		fastcgi_index index.php;
		include fastcgi_params;
		fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
		fastcgi_param PATH_INFO $fastcgi_path_info;
	}

	location ~* \.(jpg|jpeg|gif|png|css|js|ico|svg|woff|woff2|ttf|otf|eot|ttf|ttc|map|mp4|webm|ogg|ogv|webp|zip|rar|tar|gz|bz2|7z)$ {
		expires max;
		log_not_found off;
	}
}

After you have added the server block to your nginx configuration file, you can test your configuration by running the following command:

bash
nginx -t

If you get no errors, you can restart your nginx server by running the following commands:

bash
sudo systemctl restart nginx
sudo systemctl restart php-fpm

And finally, to optimize your application, you can run the following commands:

bash
php colibri optimize

If everything is done right, you can access your application by visiting your domain name in your browser.

Docker ​

If you prefer to use Docker, all requirements listed in Dockerfile file. So, you can just run:

bash
docker-compose up -d

Read more about installation with Docker in Docker section.

What is Next? ​

Woohoo! You did a great job. Your social media application is almost ready to use. However ColibriPlus is not like a refrigerator that you can just plug in and it's ready to use. It is a network full-stack application that requires some configurations and settings.

Next most important parts that must be configured are:

Developed by Mansur Terla. www.terla.me

Copyright © 2025 ColibriPlus. All rights reserved.