mirror of
https://github.com/paperless-ngx/paperless-ngx.git
synced 2025-04-02 13:45:10 -05:00
724afa59c7
This commit adds a `Dockerfile` to the root of the project, accompanied
by a `docker-compose.yml.example` for simplified deployment. The
`Dockerfile` is agnostic to whether it will be the webserver, the
consumer, or if it is run for a one-off command (i.e. creation of a
superuser, migration of the database, document export, ...).
The containers entrypoint is the `scripts/docker-entrypoint.sh` script.
This script verifies that the required permissions are set, remaps the
default users and/or groups id if required and installs additional
languages if the user wishes to.
After initialization, it analyzes the command the user supplied:
- If the command starts with a slash, it is expected that the user
wants to execute a binary file and the command will be executed
without further intervention. (Using `exec` to effectively replace
the started shell-script and not have any reaping-issues.)
- If the command does not start with a slash, the command will be
passed directly to the `manage.py` script without further
modification. (Again using `exec`.)
The default command is set to `--help`.
If the user wants to execute a command that is not meant for `manage.py`
but doesn't start with a slash, the Docker `--entrypoint` parameter can
be used to circumvent the mechanics of `docker-entrypoint.sh`.
Further information can be found in `docs/setup.rst` and in
`docs/migrating.rst`.
For additional convenience, a `Dockerfile` has been added to the `docs/`
directory which allows for easy building and serving of the
documentation. This is documented in `docs/requirements.rst`.
117 lines
3.5 KiB
ReStructuredText
117 lines
3.5 KiB
ReStructuredText
.. _requirements:
|
|
|
|
Requirements
|
|
============
|
|
|
|
You need a Linux machine or Unix-like setup (theoretically an Apple machine
|
|
should work) that has the following software installed on it:
|
|
|
|
* `Python3`_ (with development libraries, pip and virtualenv)
|
|
* `GNU Privacy Guard`_
|
|
* `Tesseract`_
|
|
* `Imagemagick`_
|
|
|
|
.. _Python3: https://python.org/
|
|
.. _GNU Privacy Guard: https://gnupg.org
|
|
.. _Tesseract: https://github.com/tesseract-ocr
|
|
.. _Imagemagick: http://imagemagick.org/
|
|
|
|
Notably, you should confirm how you access your Python3 installation. Many
|
|
Linux distributions will install Python3 in parallel to Python2, using the names
|
|
``python3`` and ``python`` respectively. The same goes for ``pip3`` and
|
|
``pip``. Using Python2 will likely break things, so make sure that you're using
|
|
the right version.
|
|
|
|
For the purposes of simplicity, ``python`` and ``pip`` is used everywhere to
|
|
refer to their Python 3 versions.
|
|
|
|
In addition to the above, there are a number of Python requirements, all of
|
|
which are listed in a file called ``requirements.txt`` in the project root.
|
|
|
|
If you're not working on a virtual environment (like Vagrant or Docker), you
|
|
should probably be using a virtualenv, but that's your call. The reasons why
|
|
you might choose a virtualenv or not aren't really within the scope of this
|
|
document. Needless to say if you don't know what a virtualenv is, you should
|
|
probably figure that out before continuing.
|
|
|
|
|
|
.. _requirements-apple:
|
|
|
|
Apple-tastic Complications
|
|
--------------------------
|
|
|
|
Some users have `run into problems`_ with installing ImageMagick on Apple
|
|
systems using HomeBrew. The solution appears to be to install ghostscript as
|
|
well as ImageMagick:
|
|
|
|
.. _run into problems: https://github.com/danielquinn/paperless/issues/25
|
|
|
|
.. code:: bash
|
|
|
|
$ brew install ghostscript
|
|
$ brew install imagemagick
|
|
|
|
|
|
.. _requirements-baremetal:
|
|
|
|
Python-specific Requirements: No Virtualenv
|
|
-------------------------------------------
|
|
|
|
If you don't care to use a virtual env, then installation of the Python
|
|
dependencies is easy:
|
|
|
|
.. code:: bash
|
|
|
|
$ pip install --user --requirement /path/to/paperless/requirements.txt
|
|
|
|
This should download and install all of the requirements into
|
|
``${HOME}/.local``. Remember that your distribution may be using ``pip3`` as
|
|
mentioned above.
|
|
|
|
|
|
.. _requirements-virtualenv:
|
|
|
|
Python-specific Requirements: Virtualenv
|
|
----------------------------------------
|
|
|
|
Using a virtualenv for this is pretty straightforward: create a virtualenv,
|
|
enter it, and install the requirements using the ``requirements.txt`` file:
|
|
|
|
.. code:: bash
|
|
|
|
$ virtualenv --python=/path/to/python3 /path/to/arbitrary/directory
|
|
$ . /path/to/arbitrary/directory/bin/activate
|
|
$ pip install --requirement /path/to/paperless/requirements.txt
|
|
|
|
Now you're ready to go. Just remember to enter your virtualenv whenever you
|
|
want to use *Paperless*.
|
|
|
|
|
|
.. _requirements-documentation:
|
|
|
|
Documentation
|
|
-------------
|
|
|
|
As generation of the documentation is not required for use of *Paperless*,
|
|
dependencies for this process are not included in ``requirements.txt``. If
|
|
you'd like to generate your own docs locally, you'll need to:
|
|
|
|
.. code:: bash
|
|
|
|
$ pip install sphinx
|
|
|
|
and then cd into the ``docs`` directory and type ``make html``.
|
|
|
|
If you are using Docker, you can use the following commands to build the
|
|
documentation and run a webserver serving it on `port 8001`_:
|
|
|
|
.. code:: bash
|
|
|
|
$ pwd
|
|
/path/to/paperless
|
|
|
|
$ docker build -t paperless:docs -f docs/Dockerfile .
|
|
$ docker run --rm -it -p "8001:8000" paperless:docs
|
|
|
|
.. _port 8001: http://127.0.0.1:8001
|