szuru/INSTALL.md

Prerequisites

In order to run szurubooru, you need to have installed following software:

• Apache 2.4+
  • mod_rewrite
  • mod_mime_magic (recommended)
• PHP 5.6.0+
  • pdo_mysql
  • imagick or gd
• MySQL or MariaDB
• composer (PHP package manager)
• npm (node.js package manager)

Optional software:

• dump-gnash, swfrender or ffmpeg for Flash thumbnails
• ffmpegthumbnailer or ffmpeg for video thumbnails

Cloning the repository

Download the repository somewhere you will it run from, or better yet, clone it with git:

cd /srv/www/
git clone https://github.com/rr-/szurubooru booru-test

Fetching dependencies

To fetch dependencies that szurubooru needs in order to run, enter following commands in the terminal:

composer update
npm update

Running grunt tasks

szurubooru uses grunt to run tasks like database upgrades and tests. In order to use grunt from the terminal, you can use:

node_modules/grunt-cli/bin/grunt [TASK]

But since it's inconvenient, you can install it globally by running as administrator:

npm install -g grunt-cli

This will add grunt to your PATH, making things much more human-friendly.

grunt [TASK]

Enabling required modules in PHP

Enable required modules in php.ini (or other configuration file, depending on your setup):

;Linux
extension=pdo_mysql.so

;Windows
extension=php_pdo_mysql.dll

In order to draw thumbnails, szurubooru needs either Imagick or gd2:

;Linux
extension=imagick.so
extension=gd.so

;Windows
extension=php_imagick.dll
extension=php_gd2.dll

Creating virtual server in Apache

In order to make szurubooru visible in your browser, you need to create a virtual server. This guide focuses on Apache web server. Note that although it should be also possible to host szurubooru with nginx, you'd need to manually translate the rules inside public_html/.htaccess into nginx configuration.

Creating virtual server for Apache comes with no surprises, basically all you need is the most basic configuration:

<VirtualHost *:80>
    ServerName example.com
    DocumentRoot /path/to/szurubooru/public_html/
</VirtualHost>

ServerName specifies the domain under which szurubooru will be hosted. DocumentRoot should point to the public_html/ directory.

Some environments / configurations require extra steps to make things work - in case you experience any problems, please consult the troubleshooting section later in this file.

Enabling required modules in Apache

Enable required modules in httpd.conf (or other configuration file, depending on your setup):

LoadModule rewrite_module mod_rewrite.so ;Linux
LoadModule rewrite_module modules/mod_rewrite.so ;Windows

Enable PHP support:

LoadModule php5_module /usr/lib/apache2/modules/libphp5.so ;Linux
LoadModule php5_module /path/to/php/php5apache2_4.dll ;Windows
AddType application/x-httpd-php .php
PHPIniDir /path/to/php/

Enable MIME auto-detection (not required, but recommended - szurubooru doesn't use file extensions, and reporting correct Content-Type to browser is always a good thing):

;Linux
LoadModule mime_magic_module mod_mime_magic.so
<IfModule mod_mime_magic.c>
    MIMEMagicFile /etc/apache2/magic
</IfModule>

;Windows
LoadModule mime_magic_module modules/mod_mime_magic.so
<IfModule mod_mime_magic.c>
    MIMEMagicFile conf/magic
</IfModule>

Overwriting configuration

Everything that can be configured is stored in data/config.ini file. In order to make changes there, copy the file and name it local.ini and place it in data/ directory as well. Make sure you don't edit the data/config.ini file itself, especially if you want to contribute.

Setting up the database

Before running szurubooru for first time, you need to set up the database. szurubooru uses MySQL, so let's fire mysql and type following:

create user 'maria' identified by 'arkadia';
create database booru_test;
grant all privileges on *.* to 'maria'@'%' with grant option;

Then you need to provide the above credentials in the configuration files as described in the previous section. Example local.ini file:

[database]
dsn = mysql:dbname=booru_test
user = maria
password = arkadia

After that, upgrade the database using following command:

grunt upgrade

This should be also executed every time database schema changes.

Compiling assets

Generally HTML templates, CSS stylesheets and JS scripts are scattered over many files. This is desirable for development environment, but creates large network overhead for production environment. In order to minify the files into smallest possible packages, run following command:

grunt build

This should create public_html/app.min.js, public_html/app.min.css and public_html/app.min.html. .htaccess is configured so that if these files exist, it will load them instead of development environment. To delete these conveniently, you can run:

grunt clean

If, for any reason, you do not wish to minify the resources, you should at least copy the dependencies fetched before to the public_html/ directory with following:

grunt copy

Creating administrator account

By now, you should be able to view szurubooru in the browser. Registering administrator account is simple - the first user to create an account automatically becomes administrator and doesn't need e-mail activation.

Troubleshooting

1. Problems with Apache virtual servers

   After reloading Apache configuration, if you find yourself unable to connect to the server, make sure that connections are open, for example, like this:

   <Directory /path/to/szurubooru/public_html/>
       Require all granted
   </Directory>
   

   (Note that Apache versions prior to 2.4 used Allow from all directive.)

   Additionally, in order to access the virtual host from your machine, make sure the domain name example.com supplied in <VirtualHost/> section is included in your hosts file (usually /etc/hosts on Linux and C:/windows/system32/drivers/etc/hosts on Windows).

   If the site doesn't work for you, make sure Apache can parse .htaccess files. If it can't, you need to set AllowOverride option to yes, for example by putting following snippet inside the <VirtualHost/> section:

   <Directory /path/to/szurubooru/public_html/>
       AllowOverride All
   </Directory>
   

2. Problems with PHP modules or registration

   Make sure your php.ini path is correct. Make sure all the modules are actually loaded by inspecting results of phpinfo() call - create small file containing:

   <?php phpinfo(); ?>
   

   Then, run it in your browser and inspect the output, looking for missing modules that were supposed to be loaded.