diff --git a/README.md b/README.md index cb29b370..2c8a762d 100644 --- a/README.md +++ b/README.md @@ -20,117 +20,15 @@ websites, this is the version to use. Alternatively if you want a version that will never have significant changes, check out one of the versioned branches. -# Requirements -- These are generally based on "whatever is in Debian Stable", because that's - conservative without being TOO painfully out of date, and is a nice target - for the unit test Docker build. -- A database: PostgreSQL 11+ / MariaDB 10.3+ / SQLite 3.27+ -- [Stable PHP](https://en.wikipedia.org/wiki/PHP#Release_history) (7.3+ as of writing) -- GD or ImageMagick +# Documentation -# Installation - -1. Download the latest release under [Releases](https://github.com/shish/shimmie2/releases). -2. Unzip shimmie into a folder on the web host -3. Create a blank database -4. Visit the folder with a web browser -5. Enter the location of the database -6. Click "install". Hopefully you'll end up at the welcome screen; if - not, you should be given instructions on how to fix any errors~ - -# Installation (Development) - -1. Download shimmie via the "Download Zip" button on the [master](https://github.com/shish/shimmie2/tree/master) branch. -2. Unzip shimmie into a folder on the web host -3. Install [Composer](https://getcomposer.org/). (If you don't already have it) -4. Run `composer install` in the shimmie folder. -5. Follow instructions noted in "Installation" starting from step 3. - -# Docker -If you just want to run shimmie inside docker, there's a pre-built image -in dockerhub - `shish2k/shimmie2` - which can be used like: -``` -docker run -p 8000 -v /my/hard/drive:/app/data shish2k/shimmie2 -``` - -If you want to build your own image from source: -``` -docker build -t shimmie . -``` - -There are various options settable with environment variables: -- `UID` / `GID` - which user ID to run as (default 1000/1000) -- `INSTALL_DSN` - specify a data source to install into, to skip the installer screen, eg - `-e INSTALL_DSN="pgsql:user=shimmie;password=6y5erdfg;host=127.0.0.1;dbname=shimmie"` - -### Upgrade from earlier versions - -I very much recommend going via each major release in turn (eg, 2.0.6 --> 2.1.3 -> 2.2.4 -> 2.3.0 rather than 2.0.6 -> 2.3.0). - -While the basic database and file formats haven't changed *completely*, it's -different enough to be a pain. - - -## Custom Configuration - -Various aspects of Shimmie can be configured to suit your site specific needs -via the file `data/config/shimmie.conf.php` (created after installation). - -Take a look at `core/sys_config.php` for the available options that can -be used. - - -#### Custom User Classes - -User classes can be added to or altered by placing them in -`data/config/user-classes.conf.php`. - -For example, one can override the default anonymous "allow nothing" -permissions like so: - -```php -new UserClass("anonymous", "base", [ - Permissions::CREATE_COMMENT => True, - Permissions::EDIT_IMAGE_TAG => True, - Permissions::EDIT_IMAGE_SOURCE => True, - Permissions::CREATE_IMAGE_REPORT => True, -]); -``` - -For a moderator class, being a regular user who can delete images and comments: - -```php -new UserClass("moderator", "user", [ - Permissions::DELETE_IMAGE => True, - Permissions::DELETE_COMMENT => True, -]); -``` - -For a list of permissions, see `core/permissions.php` - - -# Development Info - -ui-\* cookies are for the client-side scripts only; in some configurations -(eg with varnish cache) they will be stripped before they reach the server - -shm-\* CSS classes are for javascript to hook into; if you're customising -themes, be careful with these, and avoid styling them, eg: - -- shm-thumb = outermost element of a thumbnail - * data-tags - * data-post-id -- shm-toggler = click this to toggle elements that match the selector - * data-toggle-sel -- shm-unlocker = click this to unlock elements that match the selector - * data-unlock-sel -- shm-clink = a link to a comment, flash the target element when clicked - * data-clink-sel - -Please tell me if those docs are lacking in any way, so that they can be -improved for the next person who uses them +* [Install straight on disk](https://github.com/shish/shimmie2/tree/master/docs/INSTALL.md) +* [Install in docker container](https://github.com/shish/shimmie2/tree/master/docs/DOCKER.md) +* [Upgrade process](https://github.com/shish/shimmie2/tree/master/docs/UPGRADE.md) +* [Advanced config](https://github.com/shish/shimmie2/tree/master/docs/CONFIG.md) +* [Developer notes](https://github.com/shish/shimmie2/tree/master/docs/DEV.md) +* [High-performance notes](https://github.com/shish/shimmie2/tree/master/docs/SPEED.md) # Contact diff --git a/docs/CONFIG.md b/docs/CONFIG.md new file mode 100644 index 00000000..dbde78da --- /dev/null +++ b/docs/CONFIG.md @@ -0,0 +1,36 @@ +# Custom Configuration + +Various aspects of Shimmie can be configured to suit your site specific needs +via the file `data/config/shimmie.conf.php` (created after installation). + +Take a look at `core/sys_config.php` for the available options that can +be used. + + +# Custom User Classes + +User classes can be added to or altered by placing them in +`data/config/user-classes.conf.php`. + +For example, one can override the default anonymous "allow nothing" +permissions like so: + +```php +new UserClass("anonymous", "base", [ + Permissions::CREATE_COMMENT => True, + Permissions::EDIT_IMAGE_TAG => True, + Permissions::EDIT_IMAGE_SOURCE => True, + Permissions::CREATE_IMAGE_REPORT => True, +]); +``` + +For a moderator class, being a regular user who can delete images and comments: + +```php +new UserClass("moderator", "user", [ + Permissions::DELETE_IMAGE => True, + Permissions::DELETE_COMMENT => True, +]); +``` + +For a list of permissions, see `core/permissions.php` diff --git a/docs/DEV.md b/docs/DEV.md new file mode 100644 index 00000000..4a835faa --- /dev/null +++ b/docs/DEV.md @@ -0,0 +1,20 @@ +# Development Info + +ui-\* cookies are for the client-side scripts only; in some configurations +(eg with varnish cache) they will be stripped before they reach the server + +shm-\* CSS classes are for javascript to hook into; if you're customising +themes, be careful with these, and avoid styling them, eg: + +- shm-thumb = outermost element of a thumbnail + * data-tags + * data-post-id +- shm-toggler = click this to toggle elements that match the selector + * data-toggle-sel +- shm-unlocker = click this to unlock elements that match the selector + * data-unlock-sel +- shm-clink = a link to a comment, flash the target element when clicked + * data-clink-sel + +Please tell me if those docs are lacking in any way, so that they can be +improved for the next person who uses them diff --git a/docs/DOCKER.md b/docs/DOCKER.md new file mode 100644 index 00000000..0e74b6f2 --- /dev/null +++ b/docs/DOCKER.md @@ -0,0 +1,18 @@ +# Docker + +If you just want to run shimmie inside docker, there's a pre-built image +in dockerhub - `shish2k/shimmie2` - which can be used like: +``` +docker run -p 8000 -v /my/hard/drive:/app/data shish2k/shimmie2 +``` + +If you want to build your own image from source: +``` +docker build -t shimmie . +``` + +There are various options settable with environment variables: +- `UID` / `GID` - which user ID to run as (default 1000/1000) +- `INSTALL_DSN` - specify a data source to install into, to skip the installer screen, eg + `-e INSTALL_DSN="pgsql:user=shimmie;password=6y5erdfg;host=127.0.0.1;dbname=shimmie"` + diff --git a/docs/INSTALL.md b/docs/INSTALL.md new file mode 100644 index 00000000..c91f415e --- /dev/null +++ b/docs/INSTALL.md @@ -0,0 +1,27 @@ +# Requirements + +- These are generally based on "whatever is in Debian Stable", because that's + conservative without being TOO painfully out of date, and is a nice target + for the unit test Docker build. +- A database: PostgreSQL 11+ / MariaDB 10.3+ / SQLite 3.27+ +- [Stable PHP](https://en.wikipedia.org/wiki/PHP#Release_history) (7.3+ as of writing) +- GD or ImageMagick + +# Get the Code + +Two main options: + +1. Via Git (allows easiest updates via `git pull`): + * `git clone https://github.com/shish/shimmie2` + * Install [Composer](https://getcomposer.org/). (If you don't already have it) + * Run `composer install` in the shimmie folder. +2. Via Stable Release: + * Download the latest release under [Releases](https://github.com/shish/shimmie2/releases). + +# Install + +1. Create a blank database +2. Visit the install folder with a web browser +3. Enter the location of the database +4. Click "install". Hopefully you'll end up at the welcome screen; if + not, you should be given instructions on how to fix any errors~ diff --git a/SPEED.md b/docs/SPEED.md similarity index 100% rename from SPEED.md rename to docs/SPEED.md diff --git a/docs/UPGRADE.md b/docs/UPGRADE.md new file mode 100644 index 00000000..97c4a1ca --- /dev/null +++ b/docs/UPGRADE.md @@ -0,0 +1,9 @@ +# Upgrade from earlier versions + +I very much recommend going via each major release in turn (eg, 2.0.6 +-> 2.1.3 -> 2.2.4 -> 2.3.0 rather than 2.0.6 -> 2.3.0). + +While the basic database and file formats haven't changed *completely*, it's +different enough to be a pain. + +