[guest@console /code/doekaki/]$ cat README
Install instructions for Dormando's Crappy Oekaki BBS Clone.
Version 1.4.2
Copyright 2000-2005 Dormando (dormando)
With much help from Lorelai (lorelai)
Both addresses end with @rydia.net
PLEASE READ SECTION TEN IF YOU ARE UPGRADING FROM VERSION 1.4.1
OR EARLIER! Thanks!
Next estimated release date is on or before April 11th, 2005.
-----------------
Table of Contents
1. Short description of doekaki
2. Requirements
3. Setting up the basics
4. Configuration options
5. The privilege system
6. Using the administration commands
7. Styling
8. Advanced configurations
9. Frequently Asked Questions
10. Upgrading your oekaki.
----------------------------------------
Section 1 - Short Description of Doekaki
Doekaki is a replacement for the CGI programs that came with the
original "poo" oekaki. It was difficult to install, configure, and
style. Since first writing this software (around December 2000) there
have been several other oekaki CGI programs and applets written. I
continue to maintain this for fun, and plan on slowly adding more
features.
You don't necessarily need to do anything after reading section three.
If you cannot figure something out, refer back to this file for help!
As of this major release, doekaki has a few new features which sets it
aside from the rest:
- Picture escrow system. Users pick what they want to do with the
picture *after* they draw it, not before. They pick the board to put it
in, whether to save the animation, or whether to save it for later
altogether.
- Internal multiboard support. There is no need to make multiple
installs of doekaki! Put it up once, and make new boards from the
administrative interface. Real simple.
- Anonymous mode for boards. Kick it oldschool and let anyone post to
a special board in your oekaki.
- Ability to move pictures between boards. If a picture is missplaced
(in the 20 minute doodle room instead of the 60 minute doodle room),
simply MOVE it to the right place! Cuts the possibility of a user having
their work outright deleted because the moderators feel it is out of
place.
- Simple interface and install. Set it up quick, no need for a MySQL
database or uploading a hundred php files. Put up a few files, make a
few directories, set the permissions and you're ready to go. The
interfaces should only get cleaner, easier to use between releases. A
design goal is to try to keep too much frivolous crap from creeping in.
Feel free to contact me with any bugs or feature
requests/suggestion/etc. The only thing that I ask in return is that you
leave the button and link on the bottom of the page styles.
------------------------
Section 2 - Requirements
In order to run DOekaki, you must have webspace capable of running CGI
(perl, in particular). You must be able to CHMOD (change the permissions
of) some files with your file transfer client of choice, and be able to
read the rest of the manual. You will also need a decent amount of web
storage space. A large oekaki can take in upwards of 100 megabytes in
size. A small one will only take a few megabytes.
You need to obtain and place oekaki applets in order to use them. One
(shii painter) is included within the zip file. If you upload all of the
files described in section 3, it will work.
Shii Painter is not owned by us, and is distributed along with the
readme file according to the wishes of the author. The URL for the site
is here: http://hp.vector.co.jp/authors/VA016309/spainter/index_en.html
Doekaki also works with the older PaintBBS applet you might be able to
dig up here: http://www.gt.sakura.ne.jp/~ocosama/ In order to make it
work, grab it, upload the jar files into the main directory, and enable
it in the configuration editor.
---------------------------------
Section 3 - Setting up the basics
-- Doekaki requires that these files and directories below be uploaded
with the given permissions. You have to use your FTP client to change
these permissions (CHMOD), it should not be very hard to do so. All of *these*
files need to be uploaded in ASCII mode.
getpic.cgi - 755
picture.cgi - 755
data/ (directory) - 777
data/templates.tmpl - 666
pics/ (directory) - 777
There are also these required files, but you should not need to change
their permissions. All of *these* files should be uploaded in BINARY mode.
res/ (directory)
res/res.zip
res/tt.zip
PCHViewer.jar
spainter_all.jar
black.gif
doekaki-b.jpg
Run picture.cgi with your browser. If all goes well, it will install the
rest of itself into the data directory, and ask you to create an admin
account. PLEASE create this account now. Bad animals will eat you
overnight if you do not.
Now place any extra applet jar files discussed in section 2.
That's it! The default options will let the oekaki run. You should give
them a once over and change a few important values (the url for the
oekaki, mainly), but otherwise the oekaki is ready to go. Continue
reading if you want to tweak your settings.
---------------------------------
Section 4 - Configuration Options
In order to change any options in DOekaki, you must log in as the admin
user (or any user with admin privileges). From there, click on the admin
link, then click the "Edit the configuration" link.
The next page has a list of all of the options, along with their
explanations to the left. Some important values;
Main URL For the oekaki: This is possibly the only important value you
should change, aside from the next one. Without it, e-mail notifications
will not be able to lead you back to the oakaki site.
E-mail address of the oekaki administrator: Set this to the e-mail users
will see when they get notifications. So they may reply and whine at you
for sending them notices :)
Administrator approval: If abuse is an issue on your board, turn this
option on. Once a user validates their e-mail account, they must wait
further for someone with the 'validate' privilege to use the admin mode
and decide whether or not they may stay. This helps prevent bad apples
from creating dozens of abusive junk accounts.
The rest of the options are safe to play around with a bit. Some of the
obvious ones will affect how much webspace your oekaki will take up.
--------------------------------
Section 5 - The privilege system
Basic Privileges:
The privilege system allows you to fully customize your boards, from
designating moderators to creating a board which only special people (or
perhaps only you) can post to.
As explained in the 'Give or Revoke Privileges' section of DOekaki's
admin page, there are six built-in privileges available to the users.
When you first set up DOekaki, you are prompted to create the user
'admin,' which has all six privileges and is essentially a
superadministrator.
When people create a new account on DOekaki, they are automatically
given the privilege of 'user.' If you want to designate a certain
account as a moderator, i.e. give them the ability to accept new
sign-ups and to delete/move pictures to different boards, give them BOTH
'validate' and 'moderator' privileges. If you only give them 'validate,'
they will NOT be able to move or delete pictures. Similarly, if you only
give them 'moderator,' they will be unable to validate new users. DO NOT
give out the admin privilege or access to the 'admin' account unless you
trust others with superadministrator powers.
Custom privileges:
These can be created as any single word. After you create one, you can
designate a board (Main administration page -> 'Edit the Boards') to
have this required privilege in order to post. For example, you could
create a custom privilege 'foop,' then create a new board called 'The
Foop board' which requires the privilege of 'foop' to post. Unless a
user is specifically given the 'foop' privilege, they cannot post
comments or pictures to this board. In this way, you can create private
or exclusive member boards.
---------------------------------------------
Section 6 - Using the administration commands
Using the administration commands is fun and easy. For administration
sections which are not described elsewhere, they are described here.
When you log in, and have some kind of admin privilege (admin, validate,
or moderate), the admin page will show options for you to aid you in
running your oekaki.
The following commands require the admin privilege;
"Give or revoke privileges" (described in section 5)
"Nuke a user"
"Ban an IP address"
"Edit the configuration" (described in section 4)
"Edit the templates" (described in section 7)
"Edit the boards"
The following require the validate priv;
"Validate new users"
The following require the moderator priv;
"Moderate posts"
"Suspend/unsuspend a user"
"View User's Hidden Information"
Each which needs to be described here is described below.
-- Nuke a user
This command is catharsis incarnate. If you want to remove a user from
the system entirely, you nuke them. If, say, a user comes along, creates
an account, then spams crap over the last 1000 pictures in your boards,
it could take quite a while to clean up. Instead, you "nuke" them, and
everything they ever did poofs forever. If you want to disable an
account without erasing their works, simply suspend them.
-- Ban an IP address
If you have a really obnoxious user who defies reason, continually
creating accounts, hammering the board, or otherwise being a poop, you
can attempt to ban them via IP address with this. For starters, simply
copy/paste their IP addres into the form and add it. If they have a
variable IP address, you can ban a range by removing chunks of the IP.
So, say their IP address was "192.168.5.12", and they came back with the
IP address "192.168.5.175", you could try putting "192.168.5." (no
quotes) in the form and adding it. Careful, as that will remove everyone
coming from that IP range.
-- Edit the boards
DOekaki has a relatively unseen feature of easily supporting multiple
boards with one install. With this interface, you can quickly create new
boards, delete old ones, or edit current ones. When your oekaki is first
installed, you have one board, the default board. The short board name
will basically be the path and internal name for the board. "newboard"
would be a good example of something to put here, "Super happy fun time
board" is a bad idea. The full name will be the bad example from above,
"Super happy fun time board", as the name will show up as to users
visiting the oekaki.
Max pictures is the maximum number of pictures to store in the oekaki
before deleting old ones. Pictures to display is the number of pictures
to display per page while viewing a board. Enable comments, is whether
or not comments are allowed to be posted in this board. Required
privilege for posting might seem confusing. Described in the section
about privileges, you are shown how to create "custom" privileges.
Otherwise adding new ones to the system. With that, you may restrict who
may post in the board by specifying the custom privilege here.
If you want to create a "display only" board, you may create a privilege
that no one has, then move above-average pictures into the board. If you
want to create a board where only a hand-picked group of people may
post, you create a custom privilege, then give that privilege to people
who should be able to post in the board.
The last option is anonymous mode. If you enable this, folks without an
account will be able to post pictures and comments on your board! Be
very careful with this, as it is harder to moderate a board with this
enabled.
That's pretty much it, the rest should be magic.
-- Validate new users
With this you may display new users who have recently signed up. There
is a list of users who have signed up but never properly validated their
e-mail address, and there is a list of users who are awaiting
administration approval, if that option is set. Simply nuke whom you
don't want to validate, and check who gets to be validated, then submit.
-- Moderate posts
Moderating posts requires the 'moderator' privilege. When you bring up
the moderator page, you see the oekaki again with new options. The popup
menu to switch boards will let you move your moderator-self between the
different boards. The skiplinks at the bottom let you bring judgement on
different pages within a board. Please note that you may only moderate
multiple items on one page at a time.
A new popup menu should appear in the middle, with a submit button
titled "Act on Selections". The default action is to delete selected
pictures/commentModerating posts requires the 'moderator' privilege.
When you bring up the moderator page, you see the oekaki again with new
options. The popup menu to switch boards will let you move your
moderator-self between the different boards. The skiplinks at the bottom
let you bring judgement on different pages within a board. Please note
that you may only moderate multiple items on one page at a time.
A new popup menu should appear in the middle, with a submit button
titled "Act on Selections". The default action is to delete selected
pictures/comments. You may also *move* selected pictures (does not work
on comments) to other boards. If a picture is missplaced, you may easily
shovel it over to the right place. The affected users are possibly
notified of the changes, and everyone is happy with no artwork being
lost.
The IP address of where the pictures/comments came from is listed as
well. You may use this information to ban the IP address of an obnoxious
user as discussed above.
-- Suspend/Unsuspend a user
Suspending a user will remove their ability to log in, post comments,
create pictures, use the admin functions, etc. If someone is being
abusive, suspend them and yell at them :) You may unsuspend them with
the same command.
-------------------
Section 7 - Styling
The style of DOekaki is completely up to you. Click Admin -> Edit
Templates to get to a drop-down menu of each styleable part of DOekaki.
You need to know a little basic HTML in order to change the style of
DOekaki - if you don't, or if you're just a little lazy, check Rydia.net
from time to time for DOekaki theme downloads!
You will notice lots of brackets with "tmpl:someword" in it. These are
not HTML! These are template values that get replaced by DOekaki
information when the page is rendered online. You can move these around,
but you MUST keep them intact or else DOekaki will not be able to
properly replace them with non-gibberish.
Layout Customizeable options:
Main - The main layout for your DOekaki. The style of this page will
show up on every subsequent page, so make sure you edit this one first.
Always keep a back-up handy in case something goes wrong.
Picture - This is the template for each picture entry in the oekaki
board. You can alter the colors used in each, or customize how the
information (user comments, oekaki information, etc.) is displayed.
Always keep a back-up.
Information customizeable options:
Drawpaint, Shiipaint - The pages where the respective applets load.
Shiipaint's template includes both Shii Painter and Shii Painter Pro.
Painter Oekaki (drawpaint) is not included in DOekaki and must be
downloaded separately. (See Section 2.)
Custom - This lets you edit the page you see when you click 'Draw.' On
this page, you select oekaki canvas size and which painter applet you
want to use.
Commentmail - This is the e-mail sent to a user with email notifications
on, every time someone comments on their artwork.
Commentpage - Where users can write comments for their finished oekaki,
save the animation or save a picture for resuming later.
Editprofile - The page where users customize their profile.
Pchviewer - The page where you view animations.
-----------------------------------
Section 8 - Advanced Configurations
This section is aimed at folks very familiar with how CGI applications
work, and aren't afraid to change a few things.
-- Making doekaki a little more secure.
If you wish to increase your security a tad, you should move your "data"
directory outside of your web root. That way it will be much harder for
someone to browse your data directory.
So, if your webspace starts with /home/yoursite/
and your webpage is in /home/yoursite/html/
then move your data dir to /home/yoursite/doedata/
Then open up getpic.cgi and picture.cgi in your favorite non-munging
text editor, and edit the following values:
picture.cgi: my $datadir = 'data/';
change that to; my $datadir = '/home/yoursite/doedata/';
getpic.cgi: $conffile and $escrowfile. Change them according to the
picture.cgi example above.
When you move the files, make sure the permissions stay the same, or
else doekaki won't be able to use them.
--------------------------------------
Section 9 - Frequently Asked Questions
-- Does doekaki work under windows?
Not fully. All functions except for getpic.cgi's picture saving will
work. As far as I can see, the applets send the PNG data in a
not-fully-HTTP-like manner, which microsoft IIS has troubles with. I
cannot change this, as I have yet to find an applet under a Free
software license, and do not have the time and motivation to write my
own.
-- My question isn't answered here, what do I do?
E-mail me. I'll probably answer within a day. If it's a good enough
question, it'll show up here after the next release.
----------------------------------
Section 10 - Upgrading your oekaki
- From 1.4.0, 1.4.1 TO 1.4.2.
The system template for the config editor was changed. The configuration datafile will automatically be upgraded by doekaki, but you will need to change the system template by hand.
To do this: log into doekaki as an administrator, go to the template editor, select "Edit system templates" then bring up the editor for sysconfedit. Now open the templates.tmpl file from the new release of doekaki, and search for "sysconfedit" and HTML that looks similar to what you have in your browser window. Now remove everything in the browser window, and paste in the entire sysconfedit section from the templates file.
If this is too difficult (I'm sorry, the next major version might make template upgrades easier!), just upload the new templates.tmpl file over the old one, adjust permissions if needed, and re-do any customization you've done already.
Otherwise, upload the new getpic.cgi and picture.cgi. There should be no other changes.
- From 1.4.0 to 1.4.1.
This is an easy update. Just copy in the new getpic.cgi, and
picture.cgi files over the old ones. Nothing else needs to be
done.
- From 1.2.2 and below.
YOU CAN'T! :( Too much has changed. Simply make a new install and run
with it. You'll be happy.
[guest@console /code/doekaki/]$