Documented the API and added some help for the config file

This commit is contained in:
Daniel Quinn 2016-03-04 23:59:13 +00:00
parent 66df220bea
commit 1ffce8f52d
4 changed files with 64 additions and 26 deletions

23
docs/api.rst Normal file
View File

@ -0,0 +1,23 @@
.. _api:
The REST API
############
Paperless makes use of the `Django REST Framework`_ standard API interface
because of its inherent awesomeness. Conveniently, the system is also
self-documenting, so learn more about the access points, schema, what's
accepted and what isn't, you need only visit ``/api`` on your local Paperless
installation.
.. _Django REST Framework: http://django-rest-framework.org/
.. _api-uploading:
Uploading
---------
File uploads in an API are hard and so far as I've been able to tell, there's
no standard way of accepting them, so rather than crowbar file uploads into the
REST API and endure that headache, I've left that process to a simple HTTP
POST, documented on the :ref:`consumption page <consumption-http>`.

View File

@ -40,9 +40,9 @@ follow the :ref:`consumer <utilities-consumer>` instructions to get it running.
A Note on File Naming
---------------------
Any document you put into the consumption directory will be consumed, but if you
name the file right, it'll automatically set some values in the database for
you. This is is the logic the consumer follows:
Any document you put into the consumption directory will be consumed, but if
you name the file right, it'll automatically set some values in the database
for you. This is is the logic the consumer follows:
1. Try to find the correspondent, title, and tags in the file name following
the pattern: ``Correspondent - Title - tag,tag,tag.pdf``.
@ -111,11 +111,10 @@ So, with all that in mind, here's what you do to get it running:
HTTP POST
=========
Currently, the API is limited to only handling file uploads, it doesn't do tags
yet, and the URL schema isn't concrete, but it's a start. It's also not much of
a real API, it's just a URL that accepts an HTTP POST.
You can also submit a document via HTTP POST. It doesn't do tags yet, and the
URL schema isn't concrete, but it's a start.
To push your document to *Paperless*, send an HTTP POST to the server with the
To push your document to Paperless, send an HTTP POST to the server with the
following name/value pairs:
* ``correspondent``: The name of the document's correspondent. Note that there

32
paperless.conf.example Normal file
View File

@ -0,0 +1,32 @@
# Sample paperless.conf
# Copy this file to /etc/paperless.conf and modify it to suit your needs.
# This where your documents should go to be consumed. Make sure that it exists
# and that the user running the paperless service can read/write its contents
# before you start Paperless.
PAPERLESS_CONSUMPTION_DIR=""
# These values are required if you want paperless to check a particular email
# box every 10 minutes and attempt to consume documents from there. If you
# dont define a HOST, mail checking will just be disabled.
PAPERLESS_CONSUME_MAIL_HOST=""
PAPERLESS_CONSUME_MAIL_PORT=""
PAPERLESS_CONSUME_MAIL_USER=""
PAPERLESS_CONSUME_MAIL_PASS=""
# You must have a passphrase in order for Paperless to work at all. If you set
# this to "", GNUGPG will "encrypt" your PDF by writing it out as a zero-byte
# file.
# The passphrase you use here will be used when storing your documents in
# Paperless, but you can always export them in an unencrypted format by using
# document exporter. See the documentaiton for more information.
#
# One final note about the passphrase. Once you've consumed a document with
# one passphrase, DON'T CHANGE IT. Paperless assumes this to be a constant and
# can't properly export documents that were encrypted with an old passphrase if
# you've since changed it to a new one.
PAPERLESS_PASSPHRASE="secret"
# If you intend to consume documents either via HTTP POST or by email, you must
# have a shared secret here.
PAPERLESS_SHARED_SECRET=""

View File

@ -11,25 +11,9 @@ apt-get install -y tesseract-ocr tesseract-ocr-eng imagemagick
pip3 install -r /opt/paperless/requirements.txt
# Create the environment file
echo "
# This where your documents should go to be consumed. Make sure that it exists
# before you start Paperless.
PAPERLESS_CONSUMPTION_DIR='/home/vagrant/consumption'
# This is the secret passphrase used to encrypt the documents once they have
# been consumed. Change it to whatever you like, but you shouldn't change it
# after it has been used to consume a document or you won't be able to read
# that document again.
PAPERLESS_PASSPHRASE='secret'
# This is the secret string used to verify PDFs sent by mail or consumed via
# the API. If you don't plan to use either of these, you can safely leave it
# blank
PAPERLESS_SHARED_SECRET=''
" > /tmp/paperless.conf
chmod 0640 /tmp/paperless.conf
chown root:vagrant /tmp/paperless.conf
mv /tmp/paperless.conf /etc/
cat /opt/paperless/paperless.conf.example | sed -e 's#CONSUMPTION_DIR=""#CONSUMPTION_DIR="/home/vagrant/consumption"#' > /etc/paperless.conf
chmod 0640 /etc/paperless.conf
chown root:vagrant /etc/paperless.conf
# Create the consumption directory
mkdir /home/vagrant/consumption