diff --git a/INSTALL b/INSTALL new file mode 100644 index 00000000..115384da --- /dev/null +++ b/INSTALL @@ -0,0 +1,226 @@ +Prerequisites +------------- + +In order to run szurubooru, you need to have installed following software: + +- Apache2 + - mod_rewrite + - mod_mime_magic (recommended) +- PHP 5.6.0 + - pdo_sqlite + - fileinfo + - imagick or gd +- composer (PHP package manager) +- npm (node.js package manager) + +Optional modules: + +- dump-gnash or swfrender for flash thumbnails +- ffmpegthumbnailer or ffmpeg for video thumbnails + + + +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 ugprades 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_sqlite.so + ;Linux has php_fileinfo enabled by default + + ;Windows + extension=php_pdo_sqlite.dll + extension=php_fileinfo.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 + + + +Upgrading the database +---------------------- + +Every time database schema changes, you should upgrade the database by running +following grunt task in the terminal: + + grunt upgrade + + + +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 Apache2 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: + + + ServerName example.com + DocumentRoot /path/to/szurubooru/public_html/ + + +ServerName specifies the domain under which szurubooru will be hosted. +DocumentRoot should point to the public_html/ directory. + + + +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 + + MIMEMagicFile /etc/apache2/magic + + + ;Windows + LoadModule mime_magic_module modules/mod_mime_magic.so + + MIMEMagicFile conf/magic + + + +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. + + + +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. Make sure you don't +edit the file itself, especially if you want to contribute. + + + +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 After running + + + +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: + + + Require all granted + + + (Note that Apache versions prior to 2.4 used "Allow from all" directive.) + + Additionally, in order to access virtual host from your machine, make sure + the domain name "example.com" supplied in section is + included in your hosts file (usually /etc/hosts on Linux and + C:/windows/system32/drivers/etc/hosts in 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 section: + + + AllowOverride All + + + 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 phpinfo - create small file containing: + + + + Then, run it in your browser and inspect the output, looking for missing + modules that were supposed to be loaded. + + 3. "Attempt to write to read-only database" + + Make sure Apache has permission to access the database file AND directory + it's stored in. (SQLite writes temporary journal files to the parent + database directory). If you're the only user of the system, you can run + these commands without worrying too much: + + chmod 0777 data/ + chmod 0777 data/db.sqlite + + Otherwise, if you're feeling fancy, you can experiment with setfacl on + Linux or group policies on Windows.