publicfile for Debian
- - - - - - - - - - -

Documentation
=============

Documentation for publicfile is available online at
http://cr.yp.to/publicfile.html.  Run get-publicfile-docs(1) to get it
installed localy at /usr/share/doc/publicfile/html.


Usage
=====

After installation, create symlinks:

 sudo ln -s /etc/publicfile/httpd /etc/service/httpd
 sudo ln -s /etc/publicfile/ftpd /etc/service/ftpd

.  This will start the publicfile service (via one of the needed packages
runit-init, runit-sysv, runit-systemd or daemontools-run).

Pointing your webbrowser to http://localhost/ should now show

 it works

(since that's what's in

 /etc/publicfile/file/localhost/index.html

).  If you want your public files to be accessible via e.g.
http://www.example.org/, create a symlink

 ln -s localhost /etc/publicfile/file/www.example.org

(assuming www.example.org's DNS entry points to your host).


Compatibility
=============

You are encouraged to create a compatibility symlink in
/usr/local/publicfile, like this:

 sudo ln -s /etc/publicfile /usr/local/publicfile

.  This will make life easy for publicfile administrators who work on multiple
platforms, or, as D. J. Bernstein writes at http://cr.yp.to/compatibility.html:
"Breaking cross-platform compatibility for the sake of cross-package similarity
is a horrible idea."


Build time configuration, directory layout, logs
================================================

publicfile's configure is ran during postinst, as

 /usr/lib/publicfile/configure www-data www-log \
  /etc/publicfile $(hostname --fqdn) www ftp localhost

.  It creates

 /etc/publicfile/httpd/log/run
 /etc/publicfile/httpd/run

, a.o.

Logs are kept under /var/log/publicfile .  You might want to pipe them through
tai64nlocal and/or adjust /etc/service/httpd/log/run .


FAQ / Troubleshooting
=====================

publicfile doesn't seem to work for me
--------------------------------------

Check your /var/log/publicfile/httpd/current.  If it shows something like

 tcpserver: error while loading shared libraries: libc.so.6: cannot map zero-fill pages

, then you can fix the problem by first killing your publicfile process doing

 sudo svc -d /etc/service/httpd

, then edit /etc/publicfile/httpd/run and change -d50000 to -d100000.
Now start your publicfile process again by running

 sudo svc -u /etc/service/httpd

. If everything worked out fine, running

 w3m -dump http://0/

now should show you "it works" again.

PS: the low default 50000 setting is defined in publicfile-0.52/configure.c .
Patching that file and rebuilding is another way to deal with this problem.


publicfile doesn't seem to offer my pictures (.JPG files) in a sane way
-----------------------------------------------------------------------

Rename <foo>.JPG to <foo>.jpeg and it will work.  Longer answer: By default,
publicfile only serves .pdf, .jpeg, .png and a very small list of other
filename extensions (see publicfile-0.52/filetype.c) with the proper mime type.
However, the publicfile Debian package is shipped with a patch applied which
enables defining more mime types at run time.  See
update-publicfile-contenttype(1) for the details.


my browser tells me "Connection reset" when testing my publicfile-served website
--------------------------------------------------------------------------------

If your logfile shows "envdir: fatal: out of memory", fix it by cranking up the
-d setting; see the first question of this FAQ: "publicfile doesn't seem to
work for me".


See also
========

See http://mdcc.cx/publicfile/ for more information.  See
http://publicfile.org/ for an overview of publicfile patches and related
software.