INSTALL

---> INSTALLATION INSTRUCTIONS <---

THESE INSTALLATION INSTRUCTIONS ARE FOR PICOCHAN 2.7 OR ABOVE. TO FIND THE
INSTRUCTIONS FOR OLD VERSIONS, SEE THE FILES /install-pre19.txt and
/install-pre27.txt

Picochan is very easy to install. Its dependencies are:

  DEPENDENCY        TESTED VERSION   DISTRIBUTION URL
  ----------------------------------------------------------------------------
  brotli            1.0.7            https://brotli.org
  argon2            20190702         https://github.com/P-H-C/phc-winner-argon2
  sqlite            3.32.3           https://sqlite.org
  luajit            2.0.5            https://luajit.org
  corefonts         1-r7             http://corefonts.sourceforge.net
  graphicsmagick    1.3.35           http://graphicsmagick.org
  ffmpeg            4.2.4            https://ffmpeg.org
  haserl            0.9.35           http://haserl.sourceforge.net

On a freshly installed Gentoo system, Picochan was made to work by first
installing the following packages through portage. The relevant USE flags are
also given (your results may vary if you do not follow the USE flags listed,
for example, thumbnails for AV1-encoded videos may not be generated if you
do not enable the dav1d USE-flag for ffmpeg).

  app-arch/brotli
  app-crypt/argon2
  dev-db/sqlite
  dev-lang/luajit           USE="lua52compat"
  media-fonts/corefonts
  media-gfx/graphicsmagick  USE="jpeg png webp svg openmp threads bzip2 zlib"
  media-video/ffmpeg        USE="dav1d vpx x264 x265 gpl"

It is optional to install cjson to enable the use of the JSON frontend
(pico_json). If you do not install cjson, the ordinary HTML frontend will
still function.

It is optional but recommended to remove bash as your system shell (/bin/sh).
Picochan uses the functions os.execute() and io.popen(), which make use of
/bin/sh to execute commands. On most Linux systems, this is a symlink to bash.
GNU bash is highly insecure, and for security reasons, consider replacing
the /bin/sh symlink with a less insecure shell, such as app-shells/dash.

  # emerge app-shells/dash app-eselect/eselect-sh
  # eselect sh set dash

(See https://en.wikipedia.org/wiki/Shellshock_(software_bug) for more info)

Additionally, you must also install haserl which is not available through the
gentoo repositories. Fortunately, on Linux it is easy and quick to compile by
yourself.

---> HASERL <---

[[[ Important: DO NOT use haserl 0.9.36, it doesn't work. ]]]

Download the source tarball through the distribution URL provided.
When compiling haserl, make sure to use the following configure options. A
failure to use these options will most likely result in picochan not working.

  $ ./configure --enable-luashell \
                --disable-luacshell \
                --disable-bashshell \
                --disable-bash-extensions \
                --enable-subshell=lua \
                --with-lua=luajit
  $ make
  # make install

At this stage, on certain systems including OpenBSD and macOS, compilation fails
due to "lua2c.c" failing to compile. This is caused by faulty GNU build scripts.
If this is the case:

  $ cd src
  $ cc -I/usr/local/include/luajit* -o lua2c lua2c.c -lluajit-5.1

(Note: You may need to modify this command depending on your system.)

  $ cd ..
  $ make
  # make install

---> WEBSERVER CONFIGURATION <---

You may use any web server that supports CGI, but nginx is recommended. Example
configuration files can be found at https://github.com/vxiiduu/picochan-wsconf
For the nginx webserver, you will need to install nginx itself, fcgiwrap, and
(optionally) spawn-fcgi through your preferred means.

If you decide to use the example configuration files, you must still edit them
to suit your system. Consult the documentation for the web server and for any
other applications (fcgiwrap etc.) which you are using.

To start fcgiwrap, you may use the following command:

  $ fcgiwrap -f -s unix:/tmp/picochan.sock

It is recommended that instead of using the above command, you use a facility
provided by your operating system to start spawn-fcgi instead. Configure
spawn-fcgi to start fcgiwrap on /tmp/picochan.sock.

---> FINAL PREPARATIONS <---

Create the database:

  $ sqlite3 picochan.db <picochan.sql

Create the media directory:

  $ mkdir media media/icon media/thumb

Point your web browser at the picochan installation. Log in as an admin using
the username 'setup' and the password 'password'. Use this account to create a
new administrator account using your username and a different password. Then,
delete the setup account. Picochan is now ready to use.