diff --git a/INSTALL.md b/INSTALL.md index 5bb99a43..e9d78d91 100644 --- a/INSTALL.md +++ b/INSTALL.md @@ -1,28 +1,28 @@ Prerequisites ------------- -In order to run szurubooru, you need to have installed following software: +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 - - imagick or gd -- composer (PHP package manager) -- npm (node.js package manager) +- `Apache2` + - `mod_rewrite` + - `mod_mime_magic` (recommended) +- `PHP` 5.6.0 + - `pdo_sqlite` + - `imagick` or `gd` +- `composer` (`PHP` package manager) +- `npm` (`node.js` package manager) -Optional modules: +Optional software: -- dump-gnash or swfrender for flash thumbnails -- ffmpegthumbnailer or ffmpeg for video thumbnails +- `dump-gnash`, `swfrender` or `ffmpeg` for Flash thumbnails +- `ffmpegthumbnailer` or `ffmpeg` for video thumbnails Fetching dependencies --------------------- -To fetch dependencies that szurubooru needs in order to run, enter following +To fetch dependencies that `szurubooru` needs in order to run, enter following commands in the terminal: composer update @@ -30,11 +30,11 @@ commands in the terminal: -Running grunt tasks +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: +`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] @@ -43,16 +43,16 @@ administrator: npm install -g grunt-cli -This will add "grunt" to your PATH, making things much more human-friendly. +This will add `grunt` to your PATH, making things much more human-friendly. grunt [TASK] -Enabling required modules in PHP --------------------------------- +Enabling required modules in `PHP` +---------------------------------- -Enable required modules in php.ini (or other configuration file, depending on +Enable required modules in `php.ini` (or other configuration file, depending on your setup): ;Linux @@ -61,7 +61,7 @@ your setup): ;Windows extension=php_pdo_sqlite.dll -In order to draw thumbnails, szurubooru needs either imagick or gd2: +In order to draw thumbnails, `szurubooru` needs either `Imagick` or `gd2`: ;Linux extension=imagick.so @@ -86,12 +86,13 @@ following grunt task in the terminal: 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. +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 +Creating virtual server for `Apache` comes with no surprises, basically all you need is the most basic configuration: @@ -99,28 +100,28 @@ need is the most basic configuration: DocumentRoot /path/to/szurubooru/public_html/ -ServerName specifies the domain under which szurubooru will be hosted. -DocumentRoot should point to the public_html/ directory. +`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 +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: +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 +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): @@ -140,7 +141,7 @@ good thing): Creating administrator account ------------------------------ -By now, you should be able to view szurubooru in the browser. Registering +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. @@ -149,9 +150,9 @@ 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. +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. @@ -165,9 +166,9 @@ 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 +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 @@ -177,9 +178,9 @@ conveniently, you can run: Troubleshooting --------------- - 1. Problems with Apache virtual servers + 1. Problems with `Apache` virtual servers - After reloading Apache configuration, if you find yourself unable to + After reloading `Apache` configuration, if you find yourself unable to connect to the server, make sure that connections are open, for example, like this: @@ -187,37 +188,38 @@ Troubleshooting Require all granted - (Note that Apache versions prior to 2.4 used "Allow from all" directive.) + (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). + Additionally, in order to access the 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` 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 section: + 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 `` section: AllowOverride All - 2. Problems with PHP modules or registration + 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: + 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: 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" + 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: + 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 diff --git a/README.md b/README.md index 138bd58d..125bfb35 100644 --- a/README.md +++ b/README.md @@ -5,19 +5,21 @@ szurubooru ## What is it? -Szurubooru is a Danbooru-style board, a gallery where users can upload, browse, -tag and comment images, video clips and flash animations. +`szurubooru` is a Danbooru-style board, a gallery where users can upload, +browse, tag and comment images, video clips and flash animations. Its name have its roots in Polish language and has onomatopoeic meaning of scraping or scrubbing. It is pronounced *"shoorubooru"* [ˌʃuruˈburu]. ## Licensing -Please see the file named [`LICENSE`](https://github.com/rr-/szurubooru/blob/master/LICENSE). +Please see the file named +[`LICENSE`](https://github.com/rr-/szurubooru/blob/master/LICENSE). ## Installation -Please see the file named [`INSTALL.md`](https://github.com/rr-/szurubooru/blob/master/INSTALL.md). +Please see the file named +[`INSTALL.md`](https://github.com/rr-/szurubooru/blob/master/INSTALL.md). ## Bugs and feature requests @@ -29,8 +31,8 @@ please do following: to your problem, comment on that issue instead of opening a new one. 2. If you found an issue and the issue is closed, feel free to reopen it. 3. If you're reporting a bug, create an isolated and reproducible scenario. - 4. If you're filing a feature request, provide examples - what might be obvious - to you, might not be so obvious to the developers. + 4. If you're filing a feature request, provide examples - what might be + obvious to you, might not be so obvious to the developers. ## Contributing the code @@ -40,22 +42,23 @@ Here are some guidelines on how to contribute: - Respect coding standards - be consistent with existing code base. - Watch your whitespace - don't leave any characters at the end of the lines. - Always run tests before pushing. - - Before starting, see [`INSTALL.md`](https://github.com/rr-/szurubooru/blob/master/INSTALL.md). + - Before starting, see + [`INSTALL.md`](https://github.com/rr-/szurubooru/blob/master/INSTALL.md). - Use `grunt` to do automatic tasks like minifying Javascript files or running tests. Run `grunt --help` to see full list of available tasks. ## API -Szurubooru from version 0.9+ uses REST API. Currently there is no formal +`szurubooru` from version 0.9+ uses REST API. Currently there is no formal documentation; source code behind REST layer lies in `src/Controllers/` directory. In order to use the API, bear in mind that you need to: 1. Have actual user account on the server to do most things (depending on privileges). 2. Authenticate your requests: - 1. Send user credentials to `/auth`. You'll receive authentication token in + 1. Send user credentials to `/auth`. You'll receive authentication token in return. - 2. Send this token in X-Authorization-Token header on subsequent requests. + 2. Send this token in X-Authorization-Token header on subsequent requests. Developers reserve right to change API at any time with neither prior notice nor keeping backwards compatibility.