mirror of
https://github.com/paperless-ngx/paperless-ngx.git
synced 2025-04-27 10:59:27 -05:00
more documentation
This commit is contained in:
Jonas Winkler
parent
b066d51b17
commit
491bbd571a
@ -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:
|
||||
@ -68,28 +97,15 @@ 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::
|
||||
|
||||
@ -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
|
||||
##################
|
||||
|
||||
@ -19,4 +19,8 @@ places.
|
||||
/usr/local/etc/paperless.conf
|
||||
|
||||
Copy ``paperless.conf.example`` to any of these locations and adjust it to your
|
||||
needs.
|
||||
needs.
|
||||
|
||||
.. warning::
|
||||
|
||||
TBD: explain config options.
|
||||
29
docs/faq.rst
29
docs/faq.rst
@ -19,4 +19,31 @@ 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.
|
||||
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.
|
||||
|
||||
@ -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.
|
||||
@ -187,4 +184,4 @@ Moving data from sqlite to postgresql
|
||||
|
||||
TBD.
|
||||
|
||||
.. _redis: https://redis.io/
|
||||
.. _redis: https://redis.io/
|
||||
|
||||
@ -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
|
||||
#################
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user