diff --git a/docs/administration.rst b/docs/administration.rst index 36e577443..a52d7753d 100644 --- a/docs/administration.rst +++ b/docs/administration.rst @@ -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 `_. -.. 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 `. + +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 `_ 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 `, +you can use this command to move all your files after changing the naming scheme. .. warning:: diff --git a/docs/advanced_usage.rst b/docs/advanced_usage.rst index 1c4c6873c..3b48ea582 100644 --- a/docs/advanced_usage.rst +++ b/docs/advanced_usage.rst @@ -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 ################## diff --git a/docs/configuration.rst b/docs/configuration.rst index c11738b38..3ab233b3d 100644 --- a/docs/configuration.rst +++ b/docs/configuration.rst @@ -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. \ No newline at end of file + needs. + +.. warning:: + + TBD: explain config options. \ No newline at end of file diff --git a/docs/faq.rst b/docs/faq.rst index 9813a5d38..b55f5d058 100644 --- a/docs/faq.rst +++ b/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. \ No newline at end of file + 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 `:_. +You will need to update docker to the latest version to fix this issue. diff --git a/docs/setup.rst b/docs/setup.rst index 460e96cac..733ecbd0f 100644 --- a/docs/setup.rst +++ b/docs/setup.rst @@ -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 `_. +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/ diff --git a/docs/usage_overview.rst b/docs/usage_overview.rst index 344d1a1a5..dd9213a86 100644 --- a/docs/usage_overview.rst +++ b/docs/usage_overview.rst @@ -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 #################