paradizelost/paperless-ngx
1
0
Fork 0
mirror of https://github.com/paperless-ngx/paperless-ngx.git synced 2025-10-30 03:56:23 -05:00
Code Issues Packages Projects Releases Wiki Activity

more documentation

Browse Source
This commit is contained in:
Jonas Winkler
2020-11-14 14:16:57 +01:00
parent 8ff5210184
commit fdc605132d
6 changed files with 135 additions and 90 deletions
Download Patch File Download Diff File Expand all files Collapse all files

91
docs/administration.rst
View File

@@ -3,13 +3,15 @@
Administration
**************
.. _administration-backup:
Making backups
##############
.. warning::
This section is not updated to paperless-ng yet.
This section is not updated to paperless-ng yet, the exporter is a valid tool
for backups though.
So you're bored of this whole project, or you want to make a remote backup of
your files for whatever reason. This is easy to do, simply use the
@@ -28,34 +30,61 @@ Restoring
Updating paperless
##################
For the most part, all you have to do to update Paperless is run ``git pull``
on the directory containing the project files, and then rebuild the docker
image.
If a new release of paperless-ng is available, upgrading depends on how you
installed paperless-ng in the first place. The releases are available at
`release page <https://github.com/jonaswinkler/paperless-ng/releases>`_.
.. code-block:: shell-session
First of all, ensure that paperless is stopped.
.. code:: shell-session
$ cd /path/to/paperless
$ git pull
If ``git pull`` doesn't report any changes, there is no need to continue with
the remaining steps.
After that, check if ``docker-compose.yml.example`` has changed. Update your
``docker-compose.yml`` file if necessary.
.. code-block:: shell-session
$ docker-compose down
$ docker build -t jonaswinkler/paperless-ng .
$ docker-compose up -d
The docker image will take care of database migrations during startup.
After that, :ref:`make a backup <administration-backup>`.
A. If you used the docker-compose file, simply download the files of the new release,
adjust the settings in the files (i.e., the path to your consumption directory),
and replace your existing docker-compose files. Then start paperless as usual,
which will pull the new image, and update your database, if necessary:
.. code:: shell-session
$ cd /path/to/paperless
$ docker-compose up
If you see everything working, you can start paperless-ng with "-d" to have it
run in the background.
B. If you built the image yourself, grab the new archive and replace your current
paperless folder with the new contents.
After that, make the necessary adjustments to the docker-compose.yml (i.e.,
adjust your consumption directory).
Build and start the new image with:
.. code:: shell-session
$ cd /path/to/paperless
$ docker-compose build
$ docker-compose up
If you see everything working, you can start paperless-ng with "-d" to have it
run in the background.
.. hint::
You can usually keep your ``docker-compose.env`` file, since this file will
never include mandantory configuration options. However, it is worth checking
out the new version of this file, since it might have new recommendations
on what to configure.
Updating paperless without docker
=================================
Since paperless now involves a single page app that has to be built from source,
updating paperless manually is somewhat more complicated.
After grabbing the new release and unpacking the contents, do the following:
1. Update python requirements. Paperless uses
`Pipenv`_ for managing dependencies:
@@ -69,27 +98,14 @@ updating paperless manually is somewhat more complicated.
This creates a new virtual environment (or uses your existing environment)
and installs all dependencies into it.
2. You will also need to build the frontend each time a new update is pushed.
You need `npm <https://www.npmjs.com/get-npm>`_ for this.
.. code:: shell-session
$ cd src-ui
$ npm install @angular/cli
$ ng build --prod
This will build the application and move the relevant files to a location
within the django app (``src/documents/static/frontend``) at which django
expects to find the files.
3. Collect static files, namely the newly created frontend files.
2. Collect static files.
.. code:: shell-session
$ cd src
$ pipenv run python3 manage.py collectstatic --clear
4. Migrate the database.
3. Migrate the database.
.. code:: shell-session
@@ -251,8 +267,9 @@ scheduler.
Managing filenames
==================
If you use paperless' feature to assign custom filenames to your documents
(TODO ref), you can use this command to move all your files after changing
If you use paperless' feature to
:ref:`assign custom filenames to your documents <advanced-file_name_handling>`,
you can use this command to move all your files after changing
the naming scheme.
.. warning::

1
docs/advanced_usage.rst
View File

@@ -241,6 +241,7 @@ example, you can take a look at ``post-consumption-example.sh`` in the
The post consumption script cannot cancel the consumption process.
.. _advanced-file_name_handling:
File name handling
##################

4
docs/configuration.rst
View File

@@ -20,3 +20,7 @@ places.
Copy ``paperless.conf.example`` to any of these locations and adjust it to your
needs.
.. warning::
TBD: explain config options.

27
docs/faq.rst
View File

@@ -20,3 +20,30 @@ is
Dont mess with this folder. Don't change permissions and don't move
files around manually. This folder is meant to be entirely managed by docker
and paperless.
**Q:** *Will paperless-ng run on Raspberry Pi?*
**A:** The short answer is yes. The long answer is that certain parts of
Paperless will run very slow, such as the tesseract OCR. On Rasperry Pi,
try to OCR documents before feeding them into paperless so that paperless can
reuse the text. The web interface should be alot snappier, since it runs
in your browser and paperless has to do much less work to serve the data.
**Q:** *How do I install paperless-ng on Raspberry Pi?*
**A:** There is not docker image for ARM available. If you know how to build
that automatically, I'm all ears. For now, you have to grab the latest release
archive from the project page and build the image yourself. The release comes
with the front end already compiled, so you don't have to do this on the Pi.
You may encounter some issues during the build:
.. code:: shell-session
W: GPG error: http://ports.ubuntu.com/ubuntu-ports focal InRelease: At least one invalid signature was encountered.
E: The repository 'http://ports.ubuntu.com/ubuntu-ports focal InRelease' is not signed.
N: Updating from such a repository can't be done securely, and is therefore disabled by default.
N: See apt-secure(8) manpage for repository creation and user configuration details.
If this happens, look at `this thread <https://askubuntu.com/questions/1263284/>`:_.
You will need to update docker to the latest version to fix this issue.

95
docs/setup.rst
View File

@@ -6,13 +6,22 @@ Setup
Download
########
The source is currently only available via GitHub, so grab it from there,
by using ``git``:
Go to the project page on GitHub and download the
`latest release <https://github.com/jonaswinkler/paperless-ng/releases>`_.
There are multiple options available.
.. code:: bash
* Download the docker-compose files if you want to pull paperless from
Docker Hub.
* Download the archive and extract it if you want to build the docker image
yourself or want to install paperless without docker.
.. hint::
In contrast to paperless, the recommended way to get and update paperless-ng
is not to pull the entire git repository. Paperless-ng includes artifacts
that need to be compiled, and that's already done for you in the release.
$ git clone https://github.com/jonaswinkler/paperless-ng.git
$ cd paperless
Installation
############
@@ -22,10 +31,7 @@ You can go multiple routes with setting up and running Paperless:
* The `docker route`_
* The `bare metal route`_
The recommended setup route is docker, since it takes care of all dependencies
for you.
The `docker route`_ is quick & easy.
The `docker route`_ is quick & easy. This is the recommended route.
The `bare metal route`_ is more complicated to setup but makes it easier
should you want to contribute some code back.
@@ -50,12 +56,7 @@ Docker Route
.. _Docker installation guide: https://docs.docker.com/engine/installation/
.. _docker-compose installation guide: https://docs.docker.com/compose/install/
2. Create a copy of ``docker-compose.yml.example`` as ``docker-compose.yml``
and a copy of ``docker-compose.env.example`` as ``docker-compose.env``.
You'll be editing both these files: taking a copy ensures that you can
``git pull`` to receive updates without risking merge conflicts with your
modified versions of the configuration files.
3. Modify ``docker-compose.yml`` to your preferences. You should change the path
2. Modify ``docker-compose.yml`` to your preferences. You should change the path
to the consumption directory in this file. Find the line that specifies where
to mount the consumption directory:
@@ -72,7 +73,7 @@ Docker Route
Don't change the part after the colon or paperless wont find your documents.
4. Modify ``docker-compose.env``, following the comments in the file. The
3. Modify ``docker-compose.env``, following the comments in the file. The
most important change is to set ``USERMAP_UID`` and ``USERMAP_GID``
to the uid and gid of your user on the host system. This ensures that
both the docker container and you on the host machine have write access
@@ -80,10 +81,11 @@ Docker Route
1000 (the default for the first normal user on most systems), it will
work out of the box without any modifications.
5. Run ``docker-compose up -d``. This will create and start the necessary
containers.
4. Run ``docker-compose up -d``. This will create and start the necessary
containers. This will also build the image of paperless if you grabbed the
source archive.
6. To be able to login, you will need a super user. To create it, execute the
5. To be able to login, you will need a super user. To create it, execute the
following command:
.. code-block:: shell-session
@@ -93,7 +95,7 @@ Docker Route
This will prompt you to set a username, an optional e-mail address and
finally a password.
7. The default ``docker-compose.yml`` exports the webserver on your local port
6. The default ``docker-compose.yml`` exports the webserver on your local port
8000. If you haven't adapted this, you should now be able to visit your
Paperless instance at ``http://127.0.0.1:8000``. You can login with the
user and password you just created.
@@ -127,53 +129,48 @@ how you installed paperless. The important things to keep in mind are as follows
with your current paperless media and data volumes and used the default
sqlite database, **it will not use your sqlite database and it may seem
as if your documents are gone**. You may use the provided
``docker-compose.yml.sqlite.example`` script, which does not use postgresql. See
:ref:`setup-sqlite_to_psql` for details.
``docker-compose.sqlite.yml`` script instead, which does not use postgresql. See
:ref:`setup-sqlite_to_psql` for details on how to move your data from
sqlite to postgres.
* The task scheduler of paperless, which is used to execute periodic tasks
such as email checking and maintenance, requires a `redis`_ message broker
instance. The docker-compose route takes care of that.
* The layout of the folder structure for your documents and data remains the
same.
* The frontend needs to be built from source. The docker image takes care of
that.
same, so you can just plug your old docker volumes into paperless-ng and
expect it to find everything where it should be.
Migration to paperless-ng is then performed in a few simple steps:
1. Do a backup for two purposes: If something goes wrong, you still have your
1. Stop paperless.
.. code:: bash
$ cd /path/to/current/paperless
$ docker-compose down
2. Do a backup for two purposes: If something goes wrong, you still have your
data. Second, if you don't like paperless-ng, you can switch back to
paperless.
2. Replace the paperless source with paperless-ng. If you're using git, this
is done by:
3. Download the latest release of paperless-ng. You can either go with the
docker-compose files or use the archive to build the image yourself.
You can either replace your current paperless folder or put paperless-ng
in a different location. Paperless-ng will use the same docker volumes
as paperless.
.. code:: bash
4. Adjust ``docker-compose.yml`` and
``docker-compose.env`` to your needs.
See `docker route`_ for details on which edits are required.
$ git remote set-url origin https://github.com/jonaswinkler/paperless-ng
$ git pull
5. Update paperless. See :ref:`administration-updating` for details.
3. If you are using docker, copy ``docker-compose.yml.example`` to
``docker-compose.yml`` and ``docker-compose.env.example`` to
``docker-compose.env``. Make adjustments to these files as necessary.
See `docker route`_ for details.
4. Update paperless. See :ref:`administration-updating` for details.
5. Start paperless-ng.
.. code:: bash
$ docker-compose up
This will also migrate your database as usual. Verify by inspecting the
output that the migration was successfully executed. CTRL-C will then
gracefully stop the container. After that, you can start paperless-ng as
usuall with
6. Start paperless-ng.
.. code:: bash
$ docker-compose up -d
6. Paperless installed a permanent redirect to ``admin/`` in your browser. This
7. Paperless installed a permanent redirect to ``admin/`` in your browser. This
redirect is still in place and prevents access to the new UI. Clear
everything related to paperless in your browsers data in order to fix
this issue.

1
docs/usage_overview.rst
View File

@@ -45,7 +45,6 @@ Each document has a couple of fields that you can assign to them:
This text is fed into the search engine and is used for matching tags,
correspondents and document types.
.. TODO: hyperref
Frontend overview
#################