Actually, let's have the docs in the wiki
This commit is contained in:
Shish
parent
edee8e7427
commit
c3b67f346b
7 changed files with 7 additions and 315 deletions
13
README.md
13
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
|
||||
|
|
|
|||
|
|
@ -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`
|
||||
139
docs/DEV.md
139
docs/DEV.md
|
|
@ -1,139 +0,0 @@
|
|||
# Development Info
|
||||
|
||||
## Themes
|
||||
|
||||
Theme customisation is done by creating files in `themes/<theme name>`.
|
||||
|
||||
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/<extension name>/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/<theme name>/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
|
||||
|
|
@ -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 .
|
||||
```
|
||||
|
|
@ -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~
|
||||
|
|
@ -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.
|
||||
|
|
@ -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.
|
||||
Reference in a new issue