From f8592feae4b9d3aaa80844a70d6943ef9ce6db5f Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Szymon=20Jasi=C5=84ski?= Date: Fri, 14 May 2021 13:28:17 +0200 Subject: [PATCH] Documentation update (#3633) * documentation updates * development documentation updates --- README.md | 5 +-- docs/development/development_environment.md | 6 ++-- docs/development/packaging.md | 26 +++++++------- docs/installation/installation.md | 40 ++++----------------- 4 files changed, 25 insertions(+), 52 deletions(-) diff --git a/README.md b/README.md index 7cd3a6631f..ee3e1982e9 100644 --- a/README.md +++ b/README.md @@ -12,7 +12,8 @@ Features: It is an Open Source project provided on Apache v2.0 License. [![Gitter](https://img.shields.io/gitter/room/gitterHQ/gitter.svg)](https://gitter.im/allegro/ralph?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge) -[![Build Status](https://travis-ci.org/allegro/ralph.svg)](https://travis-ci.org/allegro/ralph) +[![packagecloud](https://img.shields.io/badge/deb-packagecloud.io-844fec.svg)](https://packagecloud.io/allegro/ralph) +[![Build Status](https://github.com/allegro/ralph/actions/workflows/main.yml/badge.svg)](https://github.com/allegro/ralph/actions/workflows/main.yml) [![Coverage Status](https://coveralls.io/repos/allegro/ralph/badge.svg?branch=ng&service=github)](https://coveralls.io/github/allegro/ralph?branch=ng) [![Code Health](https://landscape.io/github/allegro/ralph/ng/landscape.svg?style=flat)](https://landscape.io/github/allegro/ralph/ng) @@ -23,7 +24,7 @@ http://ralph-demo.allegro.tech/ * login: ralph * password: ralph -# Screenshots +# Screenshots ![img](https://github.com/allegro/ralph/blob/ng/docs/img/welcome-screen-1.png?raw=true) diff --git a/docs/development/development_environment.md b/docs/development/development_environment.md index dae9e62538..646f0d81b1 100644 --- a/docs/development/development_environment.md +++ b/docs/development/development_environment.md @@ -14,11 +14,11 @@ Make sure your host has the following requirements installed and properly configured, if required: -1. Python 3.5 or later +1. Python 3.6 (Ralph is tested to run on this version) 1. pip 1. virtualenvwrapper -1. NodeJS -1. npm +1. NodeJS (versions v8.10.0 - v11.7.0 are known to work) +1. npm (versions 3.5.2 - 6.5.0 are known to work) 1. mysql-client system library (on macOS install via `brew install mysql`) 1. Docker 1.13.0 or later 1. docker-compose diff --git a/docs/development/packaging.md b/docs/development/packaging.md index a2511dd3fb..a04d306a10 100644 --- a/docs/development/packaging.md +++ b/docs/development/packaging.md @@ -7,7 +7,7 @@ the latter into a package. Although this approach is not blessed by either [Debian] or Ubuntu maintainers, it provides a healthy compromise between the availability of the Ralph package and the effort required to make one. -The package is built and published to [Bintray] by the Ralph core maintainers. +The package is built and published to [packagecloud] by the Ralph core maintainers. This document describes what is necessary to know and to have for a maintainer to be able to build, test and publish the package. @@ -58,9 +58,8 @@ The process of releasing and publishing a new version is the following: ``` git push upstream ng --follow-tags ``` -9. Log in to the CI used for publishing Ralph packages and run - `ralph-release-package` job: -10. Verify the job succeeded and the Bintray repository contains the +9. Create a new GitHub release. +10. Verify the job succeeded and the packagecloud repository contains the [built version][2]. @@ -77,10 +76,10 @@ compromises: * Since IO performance for docker mounted volumes experiences severe problems on certain platforms, containers are built every time a package maintenance operation is performed. -* Official Ralph repository is owned by [Allegro], so publishing a package - requires sharing Allegro's credentials for Bintray which according to their - policy cannot be done. Therefore the script for that is going to only be - present in the CI system that is available to maintainers inside Allegro. +* Official Ralph repository is owned by [Allegro] and is hosted + in packagecloud. Package publishing action is triggered by publishing + a new release in Ralph GitHub repository. This is done by maintainers + with sufficient repository access rights. ## Building packages @@ -116,14 +115,13 @@ In order to build a release package run: make build-package ``` - > If a release package is meant to be published, a maintainer should release - > a new version prior to building one. The way to do that is described bellow. + > If a release package is meant to be published, a maintainer should manually + > create a new GitHub release. - -[1]: https://github.com/allegro.ralph -[2]: https://dl.bintray.com/allegro/debng/dists/bionic/main/binary-amd64/ +[1]: https://github.com/allegro/ralph +[2]: https://packagecloud.io/allegro/ralph [3]: ./maintainers_devtools.md -[Bintray]: https://bintray.com +[packagecloud]: https://packagecloud.io [Ubuntu]: https://ubuntu.com [Debian]: https://debian.org [Allegro]: https://allegro.pl diff --git a/docs/installation/installation.md b/docs/installation/installation.md index cea91b0c81..575c538abd 100644 --- a/docs/installation/installation.md +++ b/docs/installation/installation.md @@ -1,16 +1,10 @@ # Installation guide -For production, we provide deb packages for Ubuntu 14.04 Trusty and -Ubuntu 18.04 Bionic on the AMD64 platform. We recommend using the package -for Ubuntu 18.04. +For production, we provide deb packages for Ubuntu 18.04 Bionic +on the AMD64 platform. -The package can be installed inside a Docker container, however at the time of -this writing there is no official image yet and running the package in -a container requires some tweaks as there is no systemd inside a Docker -container (and there shouldn't be). - -It is also possible to use our old package version for Ubuntu 14.04 Trusty -distribution on the AMD64 platform. +The package can be installed inside a Docker container using allegro/ralph and +allegro/ralph-static-nginx images. ## Ubuntu package - bionic and newer - recommended @@ -32,8 +26,8 @@ used as Django settings. The steps below can be executed on any clean installation Ubuntu 18.04 Bionic. - sudo apt-key adv --keyserver hkp://keyserver.ubuntu.com:80 --recv-keys E2D0F3764B54797F - sudo sh -c "echo 'deb https://dl.bintray.com/allegro/debng bionic main' > /etc/apt/sources.list.d/ralph.list" + curl -sL https://packagecloud.io/allegro/ralph/gpgkey | sudo apt-key add - + sudo sh -c "echo 'deb https://packagecloud.io/allegro/ralph/ubuntu/ bionic main' > /etc/apt/sources.list.d/ralph.list" sudo apt-get update sudo apt-get install mysql-server nginx ralph-core @@ -118,7 +112,7 @@ If something goes wrong, you can take a peek at these log files: /var/log/ralph/gunicorn.error.log /var/log/ralph/gunicorn.access.log /var/log/nginx/ralph-error.log - /var/log/nginx/ralph-access.log + /var/log/nginx/ralph-access.log ### Next steps @@ -132,26 +126,6 @@ ssl traffic termination (or just to configure nginx to use ssl). Don't forget to read our quick start: [https://ralph-ng.readthedocs.io/en/latest/user/quickstart/](https://ralph-ng.readthedocs.io/en/latest/user/quickstart/)! -## Debian/Ubuntu package - trusty/jessie - -Make sure, your installation is clean Ubuntu 14.04, without any other packages installed, -and `apt-transport-https` installed. - - sudo apt-get update && sudo apt-get install apt-transport-https - -Now, add our official ralph repository: - - sudo apt-key adv --keyserver hkp://keyserver.ubuntu.com:80 --recv-keys 379CE192D401AB61 - sudo sh -c "echo 'deb https://dl.bintray.com/vi4m/ralph wheezy main' > /etc/apt/sources.list.d/vi4m_ralph.list" - -Then, just install ralph the traditional way: - - sudo apt-get update - sudo apt-get install ralph-core redis-server mysql-server - -Note: Main www instance of Ralph requires redis and mysql server installed. If you want to install only ralph agent somewhere, just install `ralph-core` and point it to the particular mysql and redis instance somewhere on your network. - - ### Configuration