Mercurial Repository: p/roundup/code: doc/installation.txt comparison

comparison doc/installation.txt @ 6555:34cbd0e633d2

Added FastCGI deployment info, updated Docker docs; docker-compose added This moves the Docker files to the subdirectory scripts/Docker. Attempted to provide a slightly guided install of a tracker using the roundup_start script It include the docker-compose.yml file donated by Norbert Schlemmer. Hopefully I didn't break it when modifying it for it's new home.

author	John Rouillard <rouilj@ieee.org>
date	Sun, 12 Dec 2021 19:19:52 -0500
parents	e6ae8188f61a
children	c55d56ab9ee9

comparison

equal deleted inserted replaced

-:576d630fc908
+:34cbd0e633d2
 ==================
 Installing Roundup
 ==================
 .. contents::
-:depth: 2
+:depth: 3
 :local:
 Overview
 ========
 You can also use the ``--prefix`` option to use a completely different
 base directory, if you do not want to use administrator rights. If you
 choose to do this, you may have to change Python's search path (sys.path)
 yourself.
-Creating a Docker Container
+Docker Support
-~~~~~~~~~~~~~~~~~~~~~~~~~~~
+~~~~~~~~~~~~~~
 If you don't want to install it natively, you can create a Docker
-container.  This uses the Dockerfile in the scripts directory. The
+container. This installs roundup using the `stand-alone web server`_
-roundup code in the distribuion and any changes will be used. The
+method. This is an http only install so we suggest putting an https
-build command is::
+terminating proxy in front of it.
-docker build -t roundup-app --rm -f scripts/Dockerfile .
+This is a work in progress and patches to improve it are welcome. You
+can find the docker config files under the `scripts/Docker` directory
-It supports the following backends: anydbm, sqlite, mysql and
+of the source tree.
-postgresql. Mysql and postgresql support hasn't been tested, but the
-Python modules are built and available.  See scripts/requirement.txt
+The dockerized Roundup includes database drivers for anydbm, sqlite,
-for the additional modules that are installed.
+MySQL and Postgresql (Postgresl is untested). It also includes
+additional libraries that are listed in
-If you want to build a docker from the latest release on PyPI, you can
+`scripts/Docker/requirements.txt`.
-use::
+Email support is a work in progress. Outgoing email should work given
+an external SMTP server. Reciving email should work by using a
+scheduled (cron) job to access email:
+* `As a regular job using a mailbox source`_
+* `As a regular job using a POP source`_
+* `As a regular job using an IMAP source`_
+Patches for better email support are welcome.
+If you want to use a MySQL backend, the `docker-compose.yml` file will
+deploy a Roundup container and a MySQL container backend for use with
+Roundup.
+Building a Docker Container
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
+To build a docker container using the code in the current directory,
+run this build command from the top of the source tree::
+docker build -t roundup-app -f scripts/Docker/Dockerfile .
+You can also build a container using the newest Roundup release on
+PyPI, by running::
 docker build -t roundup-app --build-arg="source=pypi" \
---rm -f scripts/Dockerfile .
+-f scripts/Docker/Dockerfile .
-Once the docker is created, run it with::
+The docker declares a single volume mounted at
+``/usr/src/app/tracker`` inside the container. You will mount your
-docker run --rm -p 9017:8080 \
+tracker home directory at this location.
--v /.../issue.tracker:/usr/src/app/tracker \
-roundup-app:latest
+Configuring Roundup in the Container
-This will make the tracker available at:
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-``http://yourhost:9017/issues/``.
+Once the docker is created using one of the build commands above, run
+an interactive session it with::
+docker run -it --rm -p 9017:8080 \
+-v $PWD/tracker:/usr/src/app/tracker roundup-app:latest
+The ``-v`` option maps a directory from the host into the docker
+container. Note that uid 1000 is used by roundup. So the uid of the
+directory (and all files under it) must be uid 1000.  This example
+assumes your tracker configs are in the tracker subdirectory. Replace
+``$PWD/tracker`` with the full path name to the directory where the
+tracker home(s) are to be stored.
 The ``-p`` option maps an external port (9017) to proxy the roundup
-server running at port 8080 to the outside. The ``-v`` option maps a
+server running at port 8080 to the outside.
-directory from the host into the docker container. It should be a
-tracker home directory. Note that uid 1000 is used by roundup. So the
+If the tracker directory is empty, the docker container will prompt
-uid of the directory must be 1000.
+you to install a tracker template and prompt you for the database
+type.
+Once you have edited and configured ``template/config.ini``, (see
+`Configuring your first tracker`) run another interactive session
+with::
+docker run --rm -it -p 9017:8080 \
+-v $PWD/tracker:/usr/src/app/tracker roundup-app:latest
+this will initialize the database and attempt to start the server.  If
+that is successful, use control-c to exit the server.
+Now start the server non-interactively (note no `-it` option) with::
+docker run -p 9017:8080 \
+-v $PWD/tracker:/usr/src/app/tracker roundup-app:latest
+Your tracker will be available at: ``http://yourhost:9017/issues/``.
+If you need to access your container while the server is running you
+can use::
+docker exec -it c0d5 sh
+where ``c0d5`` is the id prefix for the running container obtained
+from ``docker container ls``.
+Non-Guided Installation
+'''''''''''''''''''''''
+If you got a tracker installed using the automatic setup above, you
+can skip this section. To manually install and initialize the
+trackers, you can get a shell without starting the roundup-server
+using::
+docker run -it \
+-v $PWD/tracker:/usr/src/app/tracker \
+--entrypoint sh roundup-app:latest
+Now you can configure your tracker using ``roundup-admin -i tracker``
+using the directions for `Configuring your first tracker`.
+Defining Multiple Trackers
+^^^^^^^^^^^^^^^^^^^^^^^^^^
 If you want to run multiple trackers, create a subdirectory for each
-tracker home under the volume mount point. Then invoke ``docker run``
+tracker home under the volume mount point (``$PWD/tracker``). Then
-passing the roundup-server tracker specifications like::
+invoke ``docker run`` passing the roundup-server tracker
+specifications like::
 docker run --rm -p 9017:8080 \
 -v /.../issue.tracker:/usr/src/app/tracker \
-roundup-app:latest tracker1=tracker1_home  tracker2=tracker2_home
+roundup-app:latest tracker1=tracker/tracker1_home \
+tracker2=tracker/tracker2_home
 This will set up two trackers that can be reached at
 ``http://yourhost:9017/tracker1/`` and ``http://yourhost:9017/tracker2/``.
+The arguments after roundup-app:latest are tracker paths that are
-If you need to install and initialize the trackers, you can get a
+passed to roundup-server.
-shell without starting the roundup-server using::
+Docker-compose Deployment
-docker run -it \
+^^^^^^^^^^^^^^^^^^^^^^^^^
--v /.../issue.tracker:/usr/src/app/tracker \
---entrypoint sh roundup-app:latest
+If you want to run using the mysql backend, you can use docker-compose
+with ``scripts/Docker/docker-compose.yml``. This will run Roundup and
-Now you can configure your tracker using ``roundup-admin -i tracker``
+MySQL in containers. Directions for building using docker-compose are
-using the directions below.
+at the top of the yml file.
-If you need to access your container while the server is running you
-can use::
-docker exec -it c0d5 sh
-where ``c0d5`` is the id prefix for the running container.
 Configuring your first tracker
 ------------------------------
 1. To create a Roundup tracker (necessary to do before you can
 Configure a Web Interface
 -------------------------
 There are multiple web interfaces to choose from:
-1. `web server cgi-bin`_
+.. contents::
-2. `cgi-bin for limited-access hosting`_
+:depth: 1
-3. `stand-alone web server`_
+:local:
-4. `Zope product - ZRoundup`_
-5. `Apache HTTP Server with mod_wsgi`_
-6. `Apache HTTP Server with mod_python`_  (deprecated)
-7. `Nginx HTTP Server`_
-8. `WSGI Variations`_
 You may need to give the web server user permission to access the tracker home
 - see the `UNIX environment steps`_ for information. You may also need to
 configure your system in some way - see `platform-specific notes`_.
 	}
 }
 }
+FastCGI (Cherokee, Hiawatha, lighttpd)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+The Hiawatha and lighttpd web servers can run Roundup using FastCGI.
+Cherokee can run FastCGI but it also supports wsgi directly using a
+uWSGI, Gnuicorn etc.
+To run Roundup suing FastCGI, the flup_ package can be used under
+Python 2 and Python 3. We don't have a detailed config for this, but
+the basic idea can be found at:
+https://flask.palletsprojects.com/en/2.0.x/deploying/fastcgi/
+If you have deployed Roundup using FastCGI and flup we welcome example
+configuration files and instructions.
+.. _flup: https://pypi.org/project/flup/
 WSGI Variations
 ~~~~~~~~~~~~~~~
 .. index:: triple: web interface; apache; mod_wsgi
 single: wsgi; apache

Mercurial > p > roundup > code

comparison doc/installation.txt @ 6555:34cbd0e633d2