diff --git a/README.md b/README.md index 6a22698f..a02d00c3 100644 --- a/README.md +++ b/README.md @@ -17,12 +17,13 @@ # Documentation -* [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) +* [Install straight on disk](https://github.com/shish/shimmie2/wiki/Install) +* [Install in docker container](https://github.com/shish/shimmie2/wiki/Docker) +* [Upgrade process](https://github.com/shish/shimmie2/wiki/Upgrade) +* [Basic settings](https://github.com/shish/shimmie2/wiki/Settings) +* [Advanced config](https://github.com/shish/shimmie2/wiki/Advanced-Config) +* [Developer notes](https://github.com/shish/shimmie2/wiki/Development-Info) +* [High-performance notes](https://github.com/shish/shimmie2/wiki/Performance) # Contact diff --git a/docs/CONFIG.md b/docs/CONFIG.md deleted file mode 100644 index dbde78da..00000000 --- a/docs/CONFIG.md +++ /dev/null @@ -1,36 +0,0 @@ -# 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 deleted file mode 100644 index 51b66706..00000000 --- a/docs/DEV.md +++ /dev/null @@ -1,139 +0,0 @@ -# Development Info - -## Themes - -Theme customisation is done by creating files in `themes/`. - -The general idea with Shimmie theming is that each `Extension` will add a -set of `Block`s to the `Page`, then the `Page` is in charge of deciding -how they should be laid out, what they should look like, etc. - -The overall layout is controlled by `page.class.php`, where the `render()` -function will take a look at all of the separate `Block`s and turn them -into the final rendered HTML. - -Individual `Extension`s will render their content by calling functions -in `ext//theme.php` - for example the code in -`ext/comment/main.php` will display a list of comments by calling -`display_comment_list()` from `ext/comment/theme.php`. - -If a theme wants to customise how the comment list is rendered, it would -do so by creating an override file in `themes//comment.theme.php` -with contents like: - -``` -class CustomCommentTheme extends CommentTheme { - public function display_comment_list( - array $images, - int $page_number, - int $total_pages, - bool $can_post - ) { - [... render the comment list however you like here ...] - } -} -``` - - -## Events and Extensions - -An event is a little blob of data saying "something happened", possibly -"something happened, here's the specific data". Events are sent with the -`send_event()` function. Since events can store data, they can be used to -return data to the extension which sent them, for example: - -``` -$tfe = send_event(new TextFormattingEvent($original_text)); -$formatted_text = $tfe->formatted; -``` - -An extension is something which is capable of reacting to events. - - -### Useful Variables - -There are a few global variables which are pretty essential to most extensions: - -* $config -- some variety of Config subclass -* $database -- a Database object used to get raw SQL access -* $page -- a Page to holds all the loose bits of extension output -* $user -- the currently logged in User -* $cache -- an optional cache for fast key / value lookups (eg Memcache) - -Each of these can be imported at the start of a function with eg "global $page, $user;" - - -### The Hello World Extension - -Here's a simple extension which listens for `PageRequestEvent`s, and each time -it sees one, it sends out a `HelloEvent`. - -``` -// ext/hello/main.php -public class HelloEvent extends Event { - public function __construct($username) { - $this->username = $username; - } -} - -public class Hello extends Extension { - public function onPageRequest(PageRequestEvent $event) { // Every time a page request is sent - global $user; // Look at the global "currently logged in user" object - send_event(new HelloEvent($user->name)); // Broadcast a signal saying hello to that user - } - public function onHello(HelloEvent $event) { // When the "Hello" signal is recieved - $this->theme->display_hello($event->username); // Display a message on the web page - } -} -``` - -``` -// ext/hello/theme.php -public class HelloTheme extends Themelet { - public function display_hello($username) { - global $page; - $h_user = html_escape($username); // Escape the data before adding it to the page - $block = new Block("Hello!", "Hello there $h_user"); // HTML-safe variables start with "h_" - $page->add_block($block); // Add the block to the page - } -} -``` - -``` -// themes/mytheme/hello.theme.php -public class CustomHelloTheme extends HelloTheme { // CustomHelloTheme overrides HelloTheme - public function display_hello($username) { // the display_hello() function is customised - global $page; - $h_user = html_escape($username); - $page->add_block(new Block( - "Hello!", - "Hello there $h_user, look at my snazzy custom theme!" - ); - } -} -``` - - -## Cookies - -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 - - -## Fin - -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 deleted file mode 100644 index 8fbea010..00000000 --- a/docs/DOCKER.md +++ /dev/null @@ -1,20 +0,0 @@ -# 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 -``` - -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"` - - -## Build custom image - -If you want to build your own image from source: -``` -docker build -t shimmie2 . -``` diff --git a/docs/INSTALL.md b/docs/INSTALL.md deleted file mode 100644 index 01783111..00000000 --- a/docs/INSTALL.md +++ /dev/null @@ -1,27 +0,0 @@ -# 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`): - 1. `git clone https://github.com/shish/shimmie2` - 2. Install [Composer](https://getcomposer.org/). (If you don't already have it) - 3. 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/docs/SPEED.md b/docs/SPEED.md deleted file mode 100644 index c98fe559..00000000 --- a/docs/SPEED.md +++ /dev/null @@ -1,65 +0,0 @@ -Notes for any sites which require extra performance -=================================================== - -Image Serving -------------- -Firstly, make sure your webserver is configured properly and nice URLs are -enabled, so that images will be served straight from disk by the webserver -instead of via PHP. If you're serving images via PHP, then your site might -melt under the load of 5 concurrent users... - -Add a Cache ------------ -eg installing memcached, then setting -`define("CACHE_DSN", "memcache://127.0.0.1:11211")` - a bunch of stuff will -get served from the high-speed cache instead of the SQL database. - -`SPEED_HAX` ------------ -Setting this to true will make a bunch of changes which reduce the correctness -of the software and increase admin workload for the sake of speed. You almost -certainly don't want to set this, but if you do (eg you're trying to run a -site with 10,000 concurrent users on a single server), it can be a huge help. - -Notable behaviour changes: - -- Database schema upgrades are no longer automatic; you'll need to run - `php index.php db-upgrade` from the CLI each time you update the code. -- Mapping from Events to Extensions is cached - you'll need to delete - `data/cache/shm_event_listeners.php` after each code change, and after - enabling or disabling any extensions. -- Tag lists (eg alphabetic, popularity, map) are cached and you'll need - to delete them manually when you feel like it -- Anonymous users can only search for 3 tags at once -- We only show the first 500 pages of results for any query, except for - the most simple (no tags, or one positive tag) -- We only ever show the first 5,000 results for complex queries -- Only comments from the past 24 hours show up in /comment/list -- Web crawlers are blocked from creating too many nonsense searches -- The first 10 pages in the index get extra caching -- RSS is limited to 10 pages -- HTML for thumbnails is cached - -`WH_SPLITS` ------------ -Store files as `images/ab/cd/...` instead of `images/ab/...`, which can -reduce filesystem load when you have millions of images. - -Multiple Image Servers ----------------------- -Image links don't have to be `/images/$hash.$ext` on the local server, they -can be full URLs, and include weighted random parts, eg: - -`https://{fred=3,leo=1}.mysite.com/images/$hash.$ext` - the software will then -use consistent hashing to map 75% of the files to `fred.mysite.com` and 25% to -`leo.mysite.com` - then you can install Varnish or Squid or something as a -caching reverse-proxy. - -Profiling ---------- -`define()`'ing `TRACE_FILE` to a filename and `TRACE_THRESHOLD` to a number -of seconds will result in JSON event traces being dumped into that file -whenever a page takes longer than the threshold to load. These traces can -then be loaded into the chrome trace viewer (chrome://tracing/) and you'll -get a breakdown of page performance by extension, event, database, and cache -queries. diff --git a/docs/UPGRADE.md b/docs/UPGRADE.md deleted file mode 100644 index ace364b5..00000000 --- a/docs/UPGRADE.md +++ /dev/null @@ -1,22 +0,0 @@ -# Upgrading old versions - -## Get the new code (from git) - -If you got shimmie from `git`, then `git pull` should fetch the latest code -(`git checkout master` then `git pull` if you're on an old non-master branch). - -Once the new Shimmie code is ready, you'll need to make sure all the -dependencies are in place and up-to-date via `composer install`. - - -## Get the new code (.zip) - -If you got shimmie from one of the .zip downloads, you'll need to download -new code, extract it, then copy across the `data` folder from the old install -into the new one. - - -# Update database schema - -This should be automatic - next time the site is loaded, it'll see that the -current schema is out of date, and will update it.