badmanners/shimmie2
badmanners/shimmie2
Archived
1
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Actually, let's have the docs in the wiki

Browse source
This commit is contained in:
Shish 2020-03-25 11:26:33 +00:00
parent edee8e7427
commit c3b67f346b
7 changed files with 7 additions and 315 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

13
README.md
View file

@ -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

36
docs/CONFIG.md
View file

@ -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
View file

@ -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

20
docs/DOCKER.md
View file

@ -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 .
```

27
docs/INSTALL.md
View file

@ -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~

65
docs/SPEED.md
View file

@ -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.

22
docs/UPGRADE.md
View file

@ -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.