Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Documentation updates #1654

Merged
merged 3 commits into from
May 9, 2020
Merged

Documentation updates #1654

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
b2bdff7
docs: Update intro in README
atodorov May 9, 2020
a4effed
docs: Update wording & links & some inconsistencies
atodorov May 9, 2020
9dddf2b
docs: improve the Upgrading section
atodorov May 9, 2020
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
14 changes: 9 additions & 5 deletions README.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -44,11 +44,15 @@ Introduction
.. image:: https://raw.githubusercontent.com/kiwitcms/Kiwi/master/tcms/static/images/kiwi_h80.png
:alt: "Kiwi TCMS Logo"

Kiwi TCMS is the leading open source test case management system. It is written in
Python and Django. It features bug tracker integration, fast test plan
and runs search, powerful access control, test automation framework plugins and
Kiwi TCMS is the leading open source test management system for both manual and
automated testing. It features bug tracker integration, search pages,
powerful access control, test automation framework plugins, visual reports and
rich API layer.

Our mission is to transform the testing process by making it more organized,
transparent & accountable for everyone on your team; to improve engineering
productivity and participation in testing.


Brief history
-------------
Expand Down Expand Up @@ -87,8 +91,8 @@ Brief history
* Mar 2020 - `Mozilla Open Source Award winner <https://kiwitcms.org/blog/kiwi-tcms-team/2020/03/27/kiwi-tcms-is-open-source-seed-award-winner/>`_


Live demo
---------
Check it out
------------

https://public.tenant.kiwitcms.org

Expand Down
3 changes: 3 additions & 0 deletions docs/source/configuration.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -72,8 +72,11 @@ Your server/docker container clock should also match the accurate time of day!
navigation bar! All other timestamps are in the same time zone!


.. _email-settings:

E-mail settings
---------------

Kiwi TCMS supports email notifications which by default are sent over SMTP and
need to be configured via the following settings:

Expand Down
74 changes: 54 additions & 20 deletions docs/source/installing_docker.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -9,18 +9,19 @@ their documentation about download and installation options.
Pull or Build Docker image
--------------------------

You can download the official Kiwi TCMS Docker image by running::
We recommend downloading the official Kiwi TCMS Docker image by running::

docker pull kiwitcms/kiwi

Alternatively you can build an image yourself by running::
Alternatively you can build an image from source by executing::

make docker-image

this will create a Docker image with the latest Kiwi TCMS version.
By default the image tag will be ``kiwitcms/kiwi:latest``.
within a git checkout directory. This will create a Docker image with the
latest Kiwi TCMS version. By default the image tag will be
``kiwitcms/kiwi:latest``.

.. note::
.. important::

While Kiwi TCMS uses git tags when releasing new versions we do not
provide versioned docker images via Docker Hub!
Expand All @@ -29,14 +30,13 @@ By default the image tag will be ``kiwitcms/kiwi:latest``.
Start Docker compose
--------------------

Before starting Kiwi TCMS you need to clone the git repo::

git clone https://github.com/kiwitcms/Kiwi.git

Copy our
`docker-compose.yml <https://raw.githubusercontent.com/kiwitcms/Kiwi/master/docker-compose.yml>`_
and place it in a new directory!

Then you can start Kiwi TCMS by executing::

cd Kiwi/
cd path/containing/docker-compose/
docker-compose up -d


Expand All @@ -45,7 +45,9 @@ Your Kiwi TCMS instance will be accessible at https://localhost.
The above command will create two containers:

1) A web container based on the latest Kiwi TCMS image
2) A DB container based on the official centos/mariadb image
2) A DB container based on the
`centos/mariadb-103-centos7 <https://hub.docker.com/r/centos/mariadb-103-centos7>`_
image


``docker-compose`` will also create two volumes for persistent data storage:
Expand All @@ -57,6 +59,12 @@ The above command will create two containers:
To use it across the organization simply distribute the FQDN of the system
running the Docker container to all associates.

.. important::

We recommend using our ``docker-compose.yml`` file only as an example to
create your own. This is what controls your Kiwi TCMS installation. It is
best to keep your own copy under version control too!


Initial configuration of running container
------------------------------------------
Expand All @@ -65,16 +73,20 @@ You need to create the database schema by executing::

docker exec -it kiwi_web /Kiwi/manage.py migrate

Then you need to create the first user account either via the web interface
or via the command line!

.. note::

By default the first registered account will become superuser!

.. warning::

This requires working email because the account must be activated via
confirmation link sent to the email address defined during registration.
Account registration via web requires working :ref:`email-settings`
because the account must be activated via confirmation link sent to the
email address defined during registration.

If email is not configured or you prefer the command line use::
It is usually easier to create the first account via the command line::

docker exec -it kiwi_web /Kiwi/manage.py createsuperuser

Expand All @@ -84,20 +96,42 @@ Upgrading

To upgrade running Kiwi TCMS containers execute the following commands::

cd Kiwi/
git pull # to refresh docker-compose.yml
cd path/containing/docker-compose/
docker-compose down
# make docker-image if you build from source or
# !!! docker tag to keep older image version on the machine
docker pull kiwitcms/kiwi # to fetch latest version from Docker Hub
docker pull centos/mariadb # to fetch the latest version for MariaDB
docker pull centos/mariadb-103-centos7 # to fetch the latest MariaDB
docker-compose up -d
docker exec -it kiwi_web /Kiwi/manage.py migrate

.. warning::

Always make sure that you execute ``migrate`` and that it doesn't report
any errors. Migrations ensure that your database schema has been altered
to match the structure which is expected by the latest version of Kiwi TCMS!
After an upgrade+migrate is performed
``docker exec -it kiwi_web /Kiwi/manage.py showmigrations`` should always
report that all migrations have been applied!

.. important::

Kiwi TCMS does not provide versioned docker images via Docker Hub! When you
execute ``docker pull`` above you will lose the older image version which
could make it impossible to revert back in case the upgrade fails. Use
``docker tag`` before ``docker pull`` in order to keep a reference to the
older Kiwi TCMS image!

.. note::

Uploads and database data should stay intact because they are split into
separate volumes which makes upgrading very easy. However you may want to
back these up before upgrading!
separate volumes which makes upgrading very easy. Always
`backup <https://kiwitcms.org/blog/atodorov/2018/07/30/how-to-backup-docker-volumes-for-kiwi-tcms/>`_
before upgrading!


Kiwi TCMS recommends that you test the upgrade on a staging server first
in order to minimize the risk of migration failures! You should pay special
attention to the DB section changelog entries for every release!


SSL configuration
Expand Down