matthias/mayan-edms
1
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity

Automate paths in documentation

Browse Source 
Paths are now configure in docs/conf.py to ensure
consistency and avoid human error.

Signed-off-by: Roberto Rosario <roberto.rosario@mayan-edms.com>
This commit is contained in:
Roberto Rosario
2019-11-18 16:44:07 -04:00
parent ec86d7679a
commit cd5da60063
8 changed files with 66 additions and 45 deletions
Download Patch File Download Diff File Expand all files Collapse all files

3
HISTORY.rst
View File

@@ -23,6 +23,9 @@
Instead of throwing an error a sample label of
"Unknown action type" will be used and allow users to
delete the unknown state action.
- Automate paths in documentation.
- Settings chapter improvements.
- Documentation paths consistency fixes.
3.2.9 (2019-11-03)
==================

18
docs/chapters/database_conversion.rst
View File

@@ -10,11 +10,11 @@ Direct install
==============
* Make a backup of your existing SQLite database and documents by copying the
``/opt/mayan-edms/media`` folder.
``|MAYAN_MEDIA_ROOT|`` folder.
* :doc:`Upgrade to at least version 3.1.3. <../releases/3.1.3>`
* Migrate the existing SQLite database with the command ``performupgrade``::
sudo -u mayan MAYAN_MEDIA_ROOT=/opt/mayan-edms/media /opt/mayan-edms/bin/mayan-edms.py performupgrade
sudo -u mayan MAYAN_MEDIA_ROOT=|MAYAN_MEDIA_ROOT| |MAYAN_BIN| performupgrade
* Install PostgreSQL::
@@ -27,11 +27,11 @@ Direct install
* Install the Python client for PostgreSQL::
sudo -u mayan /opt/mayan-edms/bin/pip install --no-cache-dir --no-use-pep517 psycopg2==2.7.3.2
sudo -u mayan |MAYAN_PIP_BIN| install --no-cache-dir --no-use-pep517 psycopg2==2.7.3.2
* Copy the newly created fallback config file::
cp /opt/mayan-edms/media/config_backup.yml /opt/mayan-edms/media/config.yml
cp |MAYAN_MEDIA_ROOT|/config_backup.yml |MAYAN_MEDIA_ROOT|/config.yml
* Edit the configuration file to add the entry for the PostgreSQL database and
rename the SQLite database to 'old'::
@@ -44,7 +44,7 @@ Direct install
CONN_MAX_AGE: 0
ENGINE: django.db.backends.sqlite3
HOST: ''
NAME: /opt/mayan-edms/media/db.sqlite3
NAME: |MAYAN_MEDIA_ROOT|/db.sqlite3
OPTIONS: {}
PASSWORD: ''
PORT: ''
@@ -60,7 +60,7 @@ Direct install
CONN_MAX_AGE: 0
ENGINE: django.db.backends.sqlite3
HOST: ''
NAME: /opt/mayan-edms/media/db.sqlite3
NAME: |MAYAN_MEDIA_ROOT|/db.sqlite3
OPTIONS: {}
PASSWORD: ''
PORT: ''
@@ -73,7 +73,7 @@ Direct install
CONN_MAX_AGE: 0
ENGINE: django.db.backends.postgresql
HOST: '127.0.0.1'
NAME: /opt/mayan-edms/media/db.sqlite3
NAME: |MAYAN_MEDIA_ROOT|/db.sqlite3
OPTIONS: {}
PASSWORD: 'mayanuserpass'
PORT: ''
@@ -83,11 +83,11 @@ Direct install
* Migrate the new database to create the empty tables::
sudo -u mayan MAYAN_DATABASE_ENGINE=django.db.backends.postgresql MAYAN_DATABASE_NAME=mayan MAYAN_DATABASE_PASSWORD=mayanuserpass MAYAN_DATABASE_USER=mayan MAYAN_DATABASE_HOST=127.0.0.1 MAYAN_MEDIA_ROOT=/opt/mayan-edms/media /opt/mayan-edms/bin/mayan-edms.py migrate
sudo -u mayan MAYAN_DATABASE_ENGINE=django.db.backends.postgresql MAYAN_DATABASE_NAME=mayan MAYAN_DATABASE_PASSWORD=mayanuserpass MAYAN_DATABASE_USER=mayan MAYAN_DATABASE_HOST=127.0.0.1 MAYAN_MEDIA_ROOT=|MAYAN_MEDIA_ROOT| |MAYAN_BIN| migrate
* Convert the data in the SQLite and store it in the PostgreSQL database::
sudo -u mayan MAYAN_DATABASE_ENGINE=django.db.backends.postgresql MAYAN_DATABASE_NAME=mayan MAYAN_DATABASE_PASSWORD=mayanuserpass MAYAN_DATABASE_USER=mayan MAYAN_DATABASE_HOST=127.0.0.1 MAYAN_MEDIA_ROOT=/opt/mayan-edms/media /opt/mayan-edms/bin/mayan-edms.py convertdb --from=old --to=default --force
sudo -u mayan MAYAN_DATABASE_ENGINE=django.db.backends.postgresql MAYAN_DATABASE_NAME=mayan MAYAN_DATABASE_PASSWORD=mayanuserpass MAYAN_DATABASE_USER=mayan MAYAN_DATABASE_HOST=127.0.0.1 MAYAN_MEDIA_ROOT=|MAYAN_MEDIA_ROOT| |MAYAN_BIN| convertdb --from=old --to=default --force
* Update the supervisor config file to have Mayan EDMS run from the PostgreSQL database::

36
docs/chapters/deploying.rst
View File

@@ -51,7 +51,8 @@ For another setup that offers more performance and scalability refer to the
3. Create the parent directory where the project will be deployed:
------------------------------------------------------------------
``/opt/`` is a good choice as it is meant is for "software and add-on packages
that are not part of the default installation". (https://www.tldp.org/LDP/Linux-Filesystem-Hierarchy/html/opt.html)
that are not part of the default installation". (https://www.tldp.org/LDP/Linux-Filesystem-Hierarchy/html/opt.html).
Create the ``/opt`` directory if it doesn't already exists.
::
sudo mkdir /opt
@@ -63,35 +64,35 @@ For another setup that offers more performance and scalability refer to the
of the Python packages in the system.
::
sudo virtualenv /opt/mayan-edms
sudo virtualenv |MAYAN_INSTALLATION_DIRECTORY|
5. Make the mayan user the owner of the installation directory:
---------------------------------------------------------------
::
sudo chown mayan:mayan /opt/mayan-edms -R
sudo chown mayan:mayan |MAYAN_INSTALLATION_DIRECTORY| -R
6. Install Mayan EDMS from PyPI:
--------------------------------
::
sudo -u mayan /opt/mayan-edms/bin/pip install --no-cache-dir --no-use-pep517 mayan-edms
sudo -u mayan |MAYAN_PIP_BIN| install --no-cache-dir --no-use-pep517 mayan-edms
7. Install the Python client for PostgreSQL and Redis:
------------------------------------------------------
::
sudo -u mayan /opt/mayan-edms/bin/pip install --no-cache-dir --no-use-pep517 psycopg2==|PYTHON_PSYCOPG2_VERSION| redis==|PYTHON_REDIS_VERSION|
sudo -u mayan |MAYAN_PIP_BIN| install --no-cache-dir --no-use-pep517 psycopg2==|PYTHON_PSYCOPG2_VERSION| redis==|PYTHON_REDIS_VERSION|
.. note::
Platforms with the ARM CPU might also need additional requirements.
::
sudo -u mayan /opt/mayan-edms/bin/pip install --no-cache-dir --no-use-pep517 psutil==|PYTHON_PSUTIL_VERSION|
sudo -u mayan |MAYAN_PIP_BIN| install --no-cache-dir --no-use-pep517 psutil==|PYTHON_PSUTIL_VERSION|
8. Create the database for the installation:
@@ -120,17 +121,18 @@ For another setup that offers more performance and scalability refer to the
.. warning::
If this step is interrupted, even if it is later resumed, will
cause the automatic admin user to no be created in some cases. Make sure all
environment variable and values are correct. If this happens, refer to the
troubleshooting chapters: :ref:`troubleshooting-autoadmin-account` and
cause the automatic admin user to not be created in some cases. Make
sure all environment variables and values are correct. If this
happens, refer to the troubleshooting chapters:
:ref:`troubleshooting-autoadmin-account` and
:ref:`troubleshooting-admin-password`.
::
sudo -u mayan MAYAN_DATABASE_ENGINE=django.db.backends.postgresql MAYAN_DATABASE_NAME=mayan \
MAYAN_DATABASE_PASSWORD=mayanuserpass MAYAN_DATABASE_USER=mayan \
MAYAN_DATABASE_HOST=127.0.0.1 MAYAN_MEDIA_ROOT=/opt/mayan-edms/media \
/opt/mayan-edms/bin/mayan-edms.py initialsetup
MAYAN_DATABASE_HOST=127.0.0.1 MAYAN_MEDIA_ROOT=|MAYAN_MEDIA_ROOT| \
|MAYAN_BIN| initialsetup
10. Collect the static files:
@@ -140,8 +142,8 @@ For another setup that offers more performance and scalability refer to the
::
sudo -u mayan MAYAN_MEDIA_ROOT=/opt/mayan-edms/media \
/opt/mayan-edms/bin/mayan-edms.py preparestatic --noinput
sudo -u mayan MAYAN_MEDIA_ROOT=|MAYAN_MEDIA_ROOT| \
|MAYAN_BIN| preparestatic --noinput
11. Create the supervisor file at ``/etc/supervisor/conf.d/mayan.conf``:
@@ -150,8 +152,8 @@ For another setup that offers more performance and scalability refer to the
sudo MAYAN_DATABASE_ENGINE=django.db.backends.postgresql MAYAN_DATABASE_NAME=mayan \
MAYAN_DATABASE_PASSWORD=mayanuserpass MAYAN_DATABASE_USER=mayan \
MAYAN_DATABASE_HOST=127.0.0.1 MAYAN_MEDIA_ROOT=/opt/mayan-edms/media \
/opt/mayan-edms/bin/mayan-edms.py platformtemplate supervisord > /etc/supervisor/conf.d/mayan.conf
MAYAN_DATABASE_HOST=127.0.0.1 MAYAN_MEDIA_ROOT=|MAYAN_MEDIA_ROOT| \
|MAYAN_BIN| platformtemplate supervisord > /etc/supervisor/conf.d/mayan.conf
12. Configure Redis:
@@ -206,7 +208,7 @@ of a restart or power failure. The Gunicorn workers are increased to 3.
------------------------------------------
::
sudo -u mayan /opt/mayan-edms/bin/pip install --no-cache-dir --no-use-pep517 librabbitmq==|PYTHON_LIBRABBITMQ_VERSION|
sudo -u mayan |MAYAN_PIP_BIN| install --no-cache-dir --no-use-pep517 librabbitmq==|PYTHON_LIBRABBITMQ_VERSION|
3. Create the RabbitMQ user and vhost:
@@ -230,7 +232,7 @@ of a restart or power failure. The Gunicorn workers are increased to 3.
increase the number of Gunicorn workers to 3 in the line (``-w 2`` section)::
command = /opt/mayan-edms/bin/gunicorn -w 2 mayan.wsgi --max-requests 1000 --max-requests-jitter 50 --worker-class gevent --bind 0.0.0.0:8000 --timeout 120
command = |MAYAN_GUNICORN_BIN| -w 2 mayan.wsgi --max-requests 1000 --max-requests-jitter 50 --worker-class gevent --bind 0.0.0.0:8000 --timeout 120
remove the concurrency limit (or increase it) of the fast worker (remove ``--concurrency=1``).

2
docs/chapters/scaling_up.rst
View File

@@ -29,7 +29,7 @@ Increase this number to match the number of CPU cores + 1.
If you are using the direct deployment methods, change the line that reads::
command = /opt/mayan-edms/bin/gunicorn -w 2 mayan.wsgi --max-requests 500 --max-requests-jitter 50 --worker-class gevent --bind 0.0.0.0:8000 --timeout 120
command = |MAYAN_GUNICORN_BIN| -w 2 mayan.wsgi --max-requests 500 --max-requests-jitter 50 --worker-class gevent --bind 0.0.0.0:8000 --timeout 120
And increase the value of the ``-w 2`` argument. This line is found in the
``[program:mayan-gunicorn]`` section of the supervisor configuration file.

8
docs/chapters/settings.rst
View File

@@ -58,12 +58,14 @@ to be valid. You can revert manually by copy the file or by using the
Via Python settings files
=========================
Another way to configure Mayan EDMS is via Python-style, settings files.
Another way to configure Mayan EDMS and the one required when more extensive
setup is required, such as when using external Python libraries, is via
Python-style, settings files.
If Mayan EDMS was installed using the Python package a ``mayan_settings``
folder will created for this purpose. If you installed Mayan EDMS
according to the :doc:`../chapters/deploying` instructions provided in this
documentation your ``mayan_settings`` folder should be located in the directory:
``/usr/share/mayan-edms/mayan/media/mayan_settings``.
``|MAYAN_MEDIA_ROOT|/mayan_settings/``.
If Mayan EDMS was installed using Docker, the ``mayan_settings`` folder
will be found inside the install Docker volume. If you installed Mayan EDMS
@@ -100,7 +102,7 @@ For the :doc:`../chapters/deploying` method, the full import path will be
``mayan.media.mayan_settings.mysettings`` and can be passed via the
``--settings`` command line argument like this::
python manage.py runserver --settings=mayan.media.mayan_settings.mysettings
|MAYAN_BIN| runserver --settings=mayan.media.mayan_settings.mysettings
or via the ``DJANGO_SETTINGS_MODULE`` environment variable like this::

14
docs/conf.py
View File

@@ -266,8 +266,22 @@ extlinks = {
def setup(app):
BASE_DIRECTORY = '/opt/'
MAYAN_INSTALLATION_DIRECTORY = os.path.join(BASE_DIRECTORY, 'mayan-edms')
MAYAN_MEDIA_ROOT = os.path.join(MAYAN_INSTALLATION_DIRECTORY, 'media')
MAYAN_PYTHON_BIN_DIR = os.path.join(MAYAN_INSTALLATION_DIRECTORY, 'bin')
MAYAN_GUNICORN_BIN = os.path.join(MAYAN_PYTHON_BIN_DIR, 'gunicorn')
MAYAN_PIP_BIN = os.path.join(MAYAN_PYTHON_BIN_DIR, 'pip')
MAYAN_BIN = os.path.join(MAYAN_PYTHON_BIN_DIR, 'mayan-edms.py')
environment_variables = utils.load_env_file()
environment_variables['DOCKER_MAYAN_IMAGE_VERSION'] = mayan.__version__
environment_variables['MAYAN_INSTALLATION_DIRECTORY'] = MAYAN_INSTALLATION_DIRECTORY
environment_variables['MAYAN_MEDIA_ROOT'] = MAYAN_MEDIA_ROOT
environment_variables['MAYAN_PYTHON_BIN_DIR'] = MAYAN_PYTHON_BIN_DIR
environment_variables['MAYAN_GUNICORN_BIN'] = MAYAN_GUNICORN_BIN
environment_variables['MAYAN_PIP_BIN'] = MAYAN_PIP_BIN
environment_variables['MAYAN_BIN'] = MAYAN_BIN
substitutions = utils.generate_substitutions(
dictionary=environment_variables
)

16
docs/releases/3.2.10.rst
View File

@@ -24,11 +24,11 @@ If installed via Python's PIP
Remove deprecated requirements::
sudo -u mayan curl https://gitlab.com/mayan-edms/mayan-edms/raw/master/removals.txt -o /tmp/removals.txt && sudo -u mayan /opt/mayan-edms/bin/pip uninstall -y -r /tmp/removals.txt
sudo -u mayan curl https://gitlab.com/mayan-edms/mayan-edms/raw/master/removals.txt -o /tmp/removals.txt && sudo -u mayan |MAYAN_PIP_BIN| uninstall -y -r /tmp/removals.txt
Type in the console::
sudo -u mayan /opt/mayan-edms/bin/pip install mayan-edms==3.2.10
sudo -u mayan |MAYAN_PIP_BIN| install mayan-edms==3.2.10
the requirements will also be updated automatically.
@@ -69,8 +69,8 @@ recommended layout::
sudo MAYAN_DATABASE_ENGINE=django.db.backends.postgresql MAYAN_DATABASE_NAME=mayan \
MAYAN_DATABASE_PASSWORD=mayanuserpass MAYAN_DATABASE_USER=mayan \
MAYAN_DATABASE_HOST=127.0.0.1 MAYAN_MEDIA_ROOT=/opt/mayan-edms/media \
/opt/mayan-edms/bin/mayan-edms.py platformtemplate supervisord > /etc/supervisor/conf.d/mayan.conf
MAYAN_DATABASE_HOST=127.0.0.1 MAYAN_MEDIA_ROOT=|MAYAN_MEDIA_ROOT| \
|MAYAN_BIN| platformtemplate supervisord > /etc/supervisor/conf.d/mayan.conf
Edit the supervisord configuration file and update any setting the template
generator missed::
@@ -81,13 +81,13 @@ Migrate existing database schema with::
sudo -u mayan MAYAN_DATABASE_ENGINE=django.db.backends.postgresql MAYAN_DATABASE_NAME=mayan \
MAYAN_DATABASE_PASSWORD=mayanuserpass MAYAN_DATABASE_USER=mayan \
MAYAN_DATABASE_HOST=127.0.0.1 MAYAN_MEDIA_ROOT=/opt/mayan-edms/media \
/opt/mayan-edms/bin/mayan-edms.py performupgrade
MAYAN_DATABASE_HOST=127.0.0.1 MAYAN_MEDIA_ROOT=|MAYAN_MEDIA_ROOT| \
|MAYAN_BIN| performupgrade
Add new static media::
sudo -u mayan MAYAN_MEDIA_ROOT=/opt/mayan-edms/media \
/opt/mayan-edms/bin/mayan-edms.py preparestatic --noinput
sudo -u mayan MAYAN_MEDIA_ROOT=|MAYAN_MEDIA_ROOT| \
|MAYAN_BIN| preparestatic --noinput
The upgrade procedure is now complete.

14
docs/topics/troubleshooting.rst
View File

@@ -100,7 +100,7 @@ To reset the password of the admin account use the following command::
MAYAN_MEDIA_ROOT=<your Mayan media root setting> <installation directory>/bin/mayan-edms.py changepassword admin
If you followed the deploying instructions from the documentation your
``MAYAN_MEDIA_ROOT`` will be ``/opt/mayan-edms/media``.
``MAYAN_MEDIA_ROOT`` will be ``|MAYAN_MEDIA_ROOT|``.
If using a Docker image, execute the command inside the container. First you
need to know the name of the Docker container running Mayan EDMS on your setup
@@ -110,7 +110,7 @@ with::
Then execute the password reset command inside the Docker container::
docker exec -ti <your docker container name> /opt/mayan-edms/bin/mayan-edms.py changepassword admin
docker exec -ti <your docker container name> |MAYAN_BIN| changepassword admin
Another way to do this is to execute a shell inside the container to get a
command prompt::
@@ -119,7 +119,7 @@ command prompt::
And then execute the command::
/opt/mayan-edms/bin/mayan-edms.py changepassword admin
|MAYAN_BIN| changepassword admin
.. _troubleshooting-autoadmin-account:
@@ -132,10 +132,10 @@ user is created outside of the database migrations.
To create an admin super user account manually use the command::
MAYAN_MEDIA_ROOT=<your Mayan media root setting> <installation directory>/bin/mayan-edms.py createsuperuser
MAYAN_MEDIA_ROOT=|MAYAN_MEDIA_ROOT| |MAYAN_BIN| createsuperuser
If you followed the deploying instructions from the documentation your
``MAYAN_MEDIA_ROOT`` will be ``/opt/mayan-edms/media``.
``MAYAN_MEDIA_ROOT`` will be ``|MAYAN_MEDIA_ROOT|``.
If using a Docker image, execute the command inside the container. First
find you container name with::
@@ -144,7 +144,7 @@ find you container name with::
Then execute the command inside the container::
docker exec -ti <your docker container name> /opt/mayan-edms/bin/mayan-edms.py createsuperuser
docker exec -ti <your docker container name> |MAYAN_BIN| createsuperuser
Another way to do this is to execute a shell inside the container to get a
command prompt::
@@ -153,7 +153,7 @@ command prompt::
And then execute the command::
/opt/mayan-edms/bin/mayan-edms.py createsuperuser
|MAYAN_BIN| createsuperuser
************