From eda6fbeed9df59670f9824b898973a4a1bb8ea24 Mon Sep 17 00:00:00 2001
From: Jan Mach <jan.mach@cesnet.cz>
Date: Sat, 16 Oct 2021 08:44:01 +0200
Subject: [PATCH] Better descriptions of development workflow.
(Redmine issue: #7041)
---
Makefile | 21 ++++++++-------------
conf/mentat-hawat-dev.py.conf | 2 +-
doc/sphinx/_doclib/development.rst | 22 +++++++++++++++++++++-
vagrantenv/.bashrc | 16 ++++++++--------
vagrantenv/system-banner.sh | 19 ++++++++++++++-----
5 files changed, 52 insertions(+), 28 deletions(-)
diff --git a/Makefile b/Makefile
index 72bb1ad2..21e722d0 100644
--- a/Makefile
+++ b/Makefile
@@ -118,11 +118,9 @@ help:
@echo " * $(GREEN)deps-postgresql$(NC): configure required PostgreSQL user accounts and databases"
@echo " * $(GREEN)deps-translations$(NC): compile all available translations"
@echo ""
- @echo " * $(GREEN)run-mentat-dev$(NC): run development version of Mentat system"
@echo " * $(GREEN)run-webui-dev$(NC): run development web server with development configuration on $(DEV_SERVER):$(DEV_PORT)"
- @echo " * $(GREEN)run-mailserver-dev$(NC): run development mail server on $(DEV_MAIL_SERVER):$(DEV_MAIL_PORT)"
- @echo ""
- @echo " * $(GREEN)ctrl-mentat-dev COMMAND=cmd$(NC): execute mentat-controller.py with given command $(FAINT)cmd$(NC)"
+ @echo " * $(GREEN)run-mailserver-sendria$(NC): run development mail server Sendria on $(DEV_MAIL_SERVER):$(DEV_MAIL_PORT)"
+ @echo " * $(GREEN)run-mailserver-python$(NC): run python-based development mail server on $(DEV_MAIL_SERVER):$(DEV_MAIL_PORT)"
@echo ""
@echo " * $(GREEN)clean-pycs$(NC): clean up Python compiled files"
@echo " * $(GREEN)clean-build-docs$(NC): clean up documentation build directories"
@@ -345,18 +343,15 @@ deps-postgresql: FORCE
#-------------------------------------------------------------------------------
-ctrl-mentat-dev:
- mentat-controller.py --command $(COMMAND)
-
-run-mentat-dev:
- @echo "\n$(GREEN)*** Running development version of Mentat system ***$(NC)\n"
- mentat-controller.py --command start
-
run-webui-dev:
@echo "\n$(GREEN)*** Running development web server with development configuration on $(DEV_SERVER):$(DEV_PORT) ***$(NC)\n"
- HAWAT_CONFIG_FILE=$(shell realpath ./hawat.local.conf) hawat-cli run --host "0.0.0.0" --port $(DEV_PORT)
+ FLASK_ENV=development FLASK_CONFIG=development HAWAT_CONFIG_FILE=$(shell realpath ./conf/mentat-hawat-dev.py.conf) hawat-cli run --host "0.0.0.0" --port $(DEV_PORT)
+
+run-mailserver-sendria:
+ @echo "\n$(GREEN)*** Running development mail server Sendria on $(DEV_MAIL_SERVER):$(DEV_MAIL_PORT) ***$(NC)\n"
+ sendria --db /var/mentat/sendria.db --smtp-ip $(DEV_MAIL_SERVER) --smtp-port $(DEV_MAIL_PORT) --http-ip 0.0.0.0 --http-port 1080 --pidfile /var/mentat/run/sendria.pid --log-file /var/mentat/log/sendria.log
-run-mailserver-dev:
+run-mailserver-python:
@echo "\n$(GREEN)*** Running development mail server on $(DEV_MAIL_SERVER):$(DEV_MAIL_PORT) ***$(NC)\n"
$(PYTHON) -m smtpd -n -c DebuggingServer $(DEV_MAIL_SERVER):$(DEV_MAIL_PORT)
diff --git a/conf/mentat-hawat-dev.py.conf b/conf/mentat-hawat-dev.py.conf
index 752ea68b..3e620c8a 100644
--- a/conf/mentat-hawat-dev.py.conf
+++ b/conf/mentat-hawat-dev.py.conf
@@ -1,4 +1,4 @@
-# Force enable the debug mode.
+# Force the debug mode.
DEBUG = True
# Debug template file loading precedence.
diff --git a/doc/sphinx/_doclib/development.rst b/doc/sphinx/_doclib/development.rst
index 5618efe5..cc64c523 100644
--- a/doc/sphinx/_doclib/development.rst
+++ b/doc/sphinx/_doclib/development.rst
@@ -618,12 +618,18 @@ Development with Vagrant
.. note::
This is still experimental and work in progress.
+First install `Vagrant <https://www.vagrantup.com/>`__ and `VirtualBox <https://www.virtualbox.org/>`__.
+
.. code-block:: shell
curl -fsSL https://apt.releases.hashicorp.com/gpg | sudo apt-key add -
sudo apt-add-repository "deb [arch=amd64] https://apt.releases.hashicorp.com $(lsb_release -cs) main"
sudo apt update && sudo apt install vagrant
+Next fetch yourself database data, boot-up development server and connect to it via SSH:
+
+.. code-block:: shell
+
make data-fetch
vagrant up
vagrant ssh
@@ -632,16 +638,30 @@ After connecting to development machine you will be greeted with banner and some
initial tips:
.. code-block:: shell
+
+ # Alias to quickly switch to mentat user with sudo su:
+ sm # Stands for 'SuMentat'
# Alias to quickly enter work directory:
wd # Stands for 'WorkDirectory'
# Alias to enable Python virtual environment:
ve # Stands for 'VirtualEnvironment'
+Basically you should execute all these aliases in succesion to end up with a prompt like this
+and ready to work:
+
+.. code-block:: shell
+
+ (venv) mentat@mentat-devel /vagrant $
+
Keep in mind following:
* You will be connected as user ``vagrant`` with passwordless sudo privileges.
* User ``mentat`` is also with passwordless sudo privileges.
-* Users ``mentat``, ``vagrant`` and ``root`` are all superusers for local development PostgreSQL database.
+* Users ``mentat``, ``vagrant`` and ``root`` are all superusers for local development PostgreSQL database. To enter database just run ``psql [dbname]``.
+* Intended workflow is editing code in your favorite editor from outside of the box and running Mentat inside.
+* To access web interface from your host machine navigate to `https://localhost:4443 <https://localhost:4443>`__.
+* To access Flask`s development web interface from your host machine you must first launch it inside the guest box with ``make run-webui-dev`` and then navigate to `http://localhost:5000 <http://localhost:5000>`__.
+* For your convenience during development you may use awesome `Sendria <https://github.com/msztolcman/sendria>`__ service to view emails being send. First launch it from guest box with ``make run-mailserver-sendria`` and then navigate from your host machine to `http://localhost:1080 <http://localhost:1080>`__.
At this point you are all set to develop Mentat locally without cluttering your personal
workstation.
diff --git a/vagrantenv/.bashrc b/vagrantenv/.bashrc
index 0de7a5dc..3bb31227 100644
--- a/vagrantenv/.bashrc
+++ b/vagrantenv/.bashrc
@@ -57,17 +57,17 @@ if [ -n "$force_color_prompt" ]; then
fi
if [ "$color_prompt" = yes ]; then
- export GIT_PS1_SHOWDIRTYSTATE=1
- export GIT_PS1_SHOWSTASHSTATE=1
- export GIT_PS1_SHOWUNTRACKEDFILES=1
- export GIT_PS1_SHOWUPSTREAM="auto verbose"
+ # export GIT_PS1_SHOWDIRTYSTATE=1
+ # export GIT_PS1_SHOWSTASHSTATE=1
+ # export GIT_PS1_SHOWUNTRACKEDFILES=1
+ # export GIT_PS1_SHOWUPSTREAM="auto verbose"
if [[ ${EUID} == 0 ]] ; then
PS1='${debian_chroot:+($debian_chroot)}\[\033[01;31m\]\h\[\033[01;34m\] \W \$\[\033[00m\] '
#PS1='${debian_chroot:+($debian_chroot)}\[\033[01;31m\]\h\[\033[01;34m\]:\[\033[01;34m\]\w\[\033[00m\]\[\033[01;33m\]$(__git_ps1 " [%s]")\[\033[00m\]\$ '
else
- #PS1='${debian_chroot:+($debian_chroot)}\[\033[01;32m\]\u@\h\[\033[00m\] \[\033[01;34m\]\w \$\[\033[00m\] '
- PS1='${debian_chroot:+($debian_chroot)}\[\033[01;32m\]\u@\h\[\033[00m\]:\[\033[01;34m\]\w\[\033[00m\]\[\033[01;33m\]$(__git_ps1 " [%s]")\[\033[00m\]\$ '
+ PS1='${debian_chroot:+($debian_chroot)}\[\033[01;32m\]\u@\h\[\033[00m\] \[\033[01;34m\]\w \$\[\033[00m\] '
+ #PS1='${debian_chroot:+($debian_chroot)}\[\033[01;32m\]\u@\h\[\033[00m\]:\[\033[01;34m\]\w\[\033[00m\]\[\033[01;33m\]$(__git_ps1 " [%s]")\[\033[00m\]\$ '
fi
else
PS1='${debian_chroot:+($debian_chroot)}\u@\h \w \$ '
@@ -106,9 +106,9 @@ alias cd..='cd ..'
alias ..='cd ..'
alias ...='cd ../..'
alias ....='cd ../../..'
-alias wd='cd /vagrant/'
-alias ve='. /var/mentat/venv/bin/activate'
alias sm='sudo su mentat'
+alias wd='cd /vagrant/'
+alias ve='source /var/mentat/venv/bin/activate'
# enable programmable completion features (you don't need to enable
# this, if it's already enabled in /etc/bash.bashrc and /etc/profile
diff --git a/vagrantenv/system-banner.sh b/vagrantenv/system-banner.sh
index be5a73b5..56ab475b 100755
--- a/vagrantenv/system-banner.sh
+++ b/vagrantenv/system-banner.sh
@@ -10,11 +10,20 @@ echo ""
echo " Welcome to Mentat development environment"
echo " https://alchemist.cesnet.cz/mentat/doc/development/html/_doclib/development.html"
echo ""
-echo " Development repository located at: /vagrant/"
-echo " Development web interface located at: https://localhost:4443"
+echo " Development repository located at: /vagrant/"
+echo " Configuration files located at: /etc/mentat/"
+echo " Variable files located at: /var/mentat/"
+echo " Web interface located at: https://localhost:4443"
+echo " Flask web interface located at: http://localhost:5000"
+echo " Sendria web interface located at: http://localhost:1080"
echo ""
echo " Tips:"
-echo " Use alias 'wd' to quickly change to project's Work Directory."
-echo " Use alias 've' to activate project's virtual environment."
-echo " Use alias 'sm' to quickly sudo su change to 'mentat' user."
+echo " Use command alias 'sm' to quickly change to 'mentat' user with sudo su."
+echo " Use command alias 'wd' to quickly change to project's Work Directory."
+echo " Use command alias 've' to activate project's Virtual Environment."
+echo ""
+echo " Launching:"
+echo " mentat-controller.py --command start # Mentat backend system"
+echo " make run-webui-dev # Mentat web interface (5000)"
+echo " make run-mailserver-sendria # Sendria mailer service (1080)"
echo ""
--
GitLab