diff --git a/ARCHITECTURE.md b/ARCHITECTURE.md
new file mode 100644
index 0000000..3afc2ff
--- /dev/null
+++ b/ARCHITECTURE.md
@@ -0,0 +1,41 @@
+# Architecture of the container #
+
+Components
+============
+
+The container contains the following components :
+- An Ubuntu base system
+- The tini + supervisord startup and daemon control system
+- Nginx Web server
+- A backend ("novnc2") Python Web app providing an API (written with
+  Flask) on port 6079
+- A frontend VueJS Web app displayed to the user, which will wrap noVNC
+- noVNC + WebSockify providing the Web VNC client in an HTML5 canvas
+- Xvfb running the X11 server in memory
+- x11vnc exporting the X11 display through VNC
+- and all regular X applications, like the LXDE desktop and apps
+
+Wiring them all
+------------------
+
+Internally, Xvfb will be started in DISPLAY :1, then x11vnc will
+provide access to it on the default VNC port (5900).
+
+noVNC will be started listening to HTTP requests on port 6081.
+It is possible to connect directly to port 6081 of the container, to
+only use the regular noVNC Web interface (provided it is exported by
+the container).
+
+Above noVNC stands the VueJS frontend Web app provided by nginx, which
+will proxy the noVNC canvas, and will add some useful features over
+noVNC.
+
+User-oriented features
+==========================
+
+The Web frontend adds the following features :
+- upon display of the Web page, the app will detect the size of the
+  Web browser's window, and will invoke the backend API so as to make
+  sure the noVNC rendering ajusts to that size
+- provide a flash video rendering transporting the sound (???)
+
diff --git a/DEVELOPMENT.md b/DEVELOPMENT.md
index 3f0bf78..032dea0 100644
--- a/DEVELOPMENT.md
+++ b/DEVELOPMENT.md
@@ -4,7 +4,18 @@
 git clone --recursive https://github.com/fcwu/docker-ubuntu-vnc-desktop
 ```
 
-# Run in local
+or, if you have already cloned it, get submodules contents :
+```
+git submodule init; git submodule update
+```
+
+# Test local code
+
+## Test-run in container rebuilt from local repo
+
+You may edit the code in your local copy of the repo, rebuild the
+container, and test the changes:
+
 ```
 make clean
 FLAVOR=lxqt ARCH=amd64 IMAGE=ubuntu:18.04 make build
@@ -12,14 +23,19 @@ make run
 ```
 
 ## develop backend
+
+You may wish to work on the backend app. As the "make run" makes sure
+to mount the current dir contents under /src in the container, you can
+proceed as such (no compilation of the Python code):
 ```
 make shell
-supervisorctl stop web
+supervisorctl -c /etc/supervisor/supervisord.conf stop web
 cd /src/image/usr/local/lib/web/backend
 ./run.py --debug
 ```
 
 ## develop frontend
+
 ```
 cd web
 yarn add
diff --git a/Dockerfile.j2 b/Dockerfile.j2
index 5fb31df..66068bd 100644
--- a/Dockerfile.j2
+++ b/Dockerfile.j2
@@ -13,7 +13,7 @@ FROM arm32v7/{{image}} as system
 COPY --from=amd64 /usr/bin/qemu-arm-static /usr/bin/
 {%endif%}
 
-{% if localbuild %}
+{% if localbuild == 1 %}
 RUN sed -i 's#http://archive.ubuntu.com/#http://tw.archive.ubuntu.com/#' /etc/apt/sources.list; 
 {% endif %}
 
@@ -94,7 +94,7 @@ RUN apt-get update \
 ################################################################################
 FROM {{image}} as builder
 
-{% if localbuild %}
+{% if localbuild == 1 %}
 RUN sed -i 's#http://archive.ubuntu.com/#http://tw.archive.ubuntu.com/#' /etc/apt/sources.list; 
 {% endif %}
 
diff --git a/Makefile b/Makefile
index 078c5e7..a76f15d 100644
--- a/Makefile
+++ b/Makefile
@@ -1,17 +1,26 @@
 .PHONY: build run
 
+# Default values for variables
 REPO  ?= dorowu/ubuntu-desktop-lxde-vnc
 TAG   ?= latest
+# you can choose other base image versions
 IMAGE ?= ubuntu:18.04
+# use tw.archive.ubuntu.com instead of archive.ubuntu.com
 LOCALBUILD ?= 1
+# choose from supported flavors (see available ones in ./flavors/*.yml)
 FLAVOR ?= lxde
+# armhf or amd64
 ARCH ?= amd64
 
+# These files will be generated from teh Jinja templates (.j2 sources)
 templates = Dockerfile image/etc/supervisor/conf.d/supervisord.conf
 
+# Rebuild the container image
 build: $(templates)
 	docker build -t $(REPO):$(TAG) .
 
+# Test run the container
+#  the local dir will be mounted under /src read-only
 run:
 	docker run --rm \
 		-p 6080:80 -p 6081:443 \
@@ -24,9 +33,11 @@ run:
 		--name ubuntu-desktop-lxde-test \
 		$(REPO):$(TAG)
 
+# Connect inside the running container for debugging
 shell:
 	docker exec -it ubuntu-desktop-lxde-test bash
 
+# Generate the SSL/TLS config for HTTPS
 gen-ssl:
 	mkdir -p ssl
 	openssl req -x509 -nodes -days 365 -newkey rsa:2048 \
@@ -34,7 +45,12 @@ gen-ssl:
 
 clean:
 	rm -f $(templates)
-		
+
+extra-clean:
+	docker rmi $(REPO):$(TAG)
+	docker image prune -f
+
+# Run jinja2cli to parse Jinja template applying rules defined in the flavors definitions
 %: %.j2 flavors/$(FLAVOR).yml
 	docker run -v $(shell pwd):/data vikingco/jinja2cli \
 		-D flavor=$(FLAVOR) \