Installation Guide

This page covers how to install vichan.

Base Requirements

1. PHP >= 7.4
2. MySQL/MariaDB server
3. mbstring
4. PHP GD
5. PHP PDO
6. PHP BCMath
7. Composer
8. A Unix-like OS

We try to make sure vichan is compatible with all major web servers. vichan does not include an Apache `.htaccess` file nor does it need one.

Recommended

1. MySQL/MariaDB server >= 5.5.3
2. ImageMagick (command-line ImageMagick or GraphicsMagick preferred).
3. APCu (Alternative PHP Cache), Memcached or Redis
4. Gifsicle

If you have zero experience running a website, landchad.net has a nice guide on how to set up a web server. Ubuntu is by far the easiest OS to use to set up any server.

Downloading Vichan

It is recommended that you utilize git clone to install vichan. This will install the latest version of the software.

Make sure you have navigated in your terminal to whichever directory your webserver is in (commonly /var/www/), or cd /var/www/.

Then clone the repository by entering git clone https://github.com/vichan-devel/vichan.git FolderName (with FolderName being optional). You may need to install git first.

After this finishes, if you did not specify a destination folder you may opt to move the resulting folder (named vichan) to something else (mv vichan NewFolderName).

Next, enter your vichan folder (cd vichan) and run composer (composer install).

If you do not have all needed dependencies installed, composer may fail, in which case it will tell you what is needed.

Configuring the Web server

Vichan does not require much of a modified configuration to work.

If you are on the fence on which server to use, Nginx is more commonly used and is notably faster on larger websites. Apache, on the other hand, works more "out of the box" and may be easier to understand if less experienced with running a server. Both servers work well with vichan.

Apache

After installing apache, a simple config like this will work well. This should be located within your /etc/apache2/sites-available directory (this is in /etc/httpd/sites-available for centos or fedora):

<VirtualHost *:80>
	ServerName example.com
	ServerAlias www.example.com # Optional
	<Directory /var/www/YourVichanFolder>
    		Options -Indexes +FollowSymLinks
    		AllowOverride All
    		Require all granted
	</Directory>

	ServerAdmin webmaster@localhost
	DocumentRoot /var/www/YourVichanFolder
	ErrorLog ${APACHE_LOG_DIR}/error.log
	CustomLog ${APACHE_LOG_DIR}/access.log combined

    ErrorDocument 403 /static/403.html
    ErrorDocument 404 /static/404.html
</VirtualHost>

The following site config disables directory listing. Then utilize a2ensite yoursiteconfig and reload apache to start your website.

Nginx

A nginx config similar to the following will work for vichan. Make sure that php-fpm is installed (apt-get install php-fpm or dnf install php-fpm).

server {
    server_name example.com www.example.com;
    root /var/www/YourVichanFolder;

    location / {
        try_files $uri $uri/ =404;
    }
    location ~ \.php$ {
        include snippets/fastcgi-php.conf;
        fastcgi_pass unix:/var/run/php/php8.3-fpm.sock; # Replace with the version of php you are running.
    }
    error_page 403 /static/403.html;
    error_page 404 /static/404.html;
}

You may also want to edit either the above config or nginx.conf (within the server or http block respectively) to add the following line, which will allow files larger than 1mb.

client_max_body_size 100M; #100 megabytes

MySQL

Vichan will not create a database for you, so you will have to do it yourself. You can use this guide if you do not know how creating users in MySQL/MariaDB works. Or this guide for databases.

All that is needed is to create a user (or use an existing user), create the database, then give that user all permissions for said database.

File Permissions

The following files and folders either need to be given to www-data or given 777 permissions:

• the root vichan directory (non-recursively)
• inc/secrets.php
• templates/cache (recursively)
• tmp/cache (recursively)

Install.php

After all above steps are followed, then install.php will begin to function. If it shows a white screen, make sure you ran composer. If you already ran it, check your php-fpm or apache logs to see what is going on.

Install.php will first show the following screen. Make sure to read and accept the agreement.

• 
• 

  After accepting the TOS, this screen appears. The file permissions were not yet set in this pictured screenshot.