csTimer development onboarding

[afedotov]

csTimer development onboarding

This is a guide how to build and run csTimer instance locally for development or other purposes.

It is required that you have Java 8 JRE and GNU Make for building production version of csTimer. And you need only PHP CLI for running development uncompressed version. If you need to develop/test functions which depends on secure HTTPS connection, including bluetooth connectivity or access from mobile devices, you need to use any kind of HTTP-server with SSL/TLS support, like Apache or nginx, or use some kind of ingress service like ngrok.

The easiest way to get all tools without worrying about how to install them is to use Docker. Using Docker you always get repeatable environment with required tools/versions, without clutter up your host machine and making dependency collisions with other project you developing. Assuming you have Docker or compatible replacement like Podman already installed on your system, follow these steps to setup your environment for running csTimer:

1. Checkout csTimer git repo:

$ git clone https://github.com/cs0x7f/cstimer.git
$ cd cstimer

Only if you plan to submit a Pull Request, create repository fork using gh CLI:

$ gh repo fork --remote

2. Setup local git repository:

These files are tracked and always being modified during production build, but typically you should not commit changes to them. Therefore we just skip them from working tree to avoid distraction:

$ git update-index --skip-worktree dist/cache.manifest
$ git update-index --skip-worktree dist/sw.js

Locally ignore all script and SSL certificate files you will create further:

$ echo '*.sh' >> .git/info/exclude
$ echo '*.pem' >> .git/info/exclude

3. Pull Docker images:

$ docker pull cimg/openjdk:8.0-node
$ docker pull php:apache

4. Add build scripts:

Create in the repo root directory following shell script files and set them executable:

make.sh

This script will be used to start GNU Make using Docker container with required tools available inside.

#!/usr/bin/env bash
#

[[ -f 'Makefile' ]] || { 
    echo "ERROR: Run this script from project root directory"
    exit 1
}

docker run \
    --name cstimer_build \
    -a STDIN -a STDOUT -a STDERR \
    --rm \
    -v "$(pwd):/mnt/cstimer" \
    -w /mnt/cstimer \
    cimg/openjdk:8.0-node \
    /usr/bin/env make "$@"

serve.sh

This script will be used to start Apache HTTP-server with PHP to serve csTimer application.

#!/usr/bin/env bash
#

[[ -f 'Makefile' ]] || { 
    echo "ERROR: Run this script from project root directory"
    exit 1
}

if [[ "$1" == "prod" ]]; then
    DOCROOT="$(pwd)/dist"
else
    DOCROOT="$(pwd)/src"
fi

echo
echo "Mode: ${1:-dev}"
echo "DocumentRoot: $DOCROOT"
echo "csTimer local HTTP URL: http://localhost:8080/"
echo "csTimer local HTTPS URL: https://localhost:8443/"
echo

docker run \
    --name cstimer_serve \
    --hostname localhost \
    -a STDIN -a STDOUT -a STDERR \
    --rm \
    -p 8080:80 \
    -p 8443:443 \
    -v "$DOCROOT:/var/www/html" \
    -v "$(pwd):/mnt/cstimer" \
    php:apache \
    /mnt/cstimer/entrypoint.sh

entrypoint.sh

This script is intended to run only as ENTRYPOINT inside Apache docker container, and should not be run manually. This entrypoint script will properly configure Apache HTTP-server in the container, and automatically create self-signed SSL certificate for localhost, unless you provide own.

#!/usr/bin/env bash
#

set -e

[[ -f '/.dockerenv' ]] || {
    echo "ERROR: This script is intended to run inside docker container as entrypoint, don't run it manually!!!"
    exit 1
}

# enable Apache SSL module
ln -s /etc/apache2/mods-available/ssl.load /etc/apache2/mods-enabled/ssl.load
# enable SSL site configuration
ln -s /etc/apache2/sites-available/default-ssl.conf /etc/apache2/sites-enabled/default-ssl.conf

# Generate if not provided and install SSL certs
[[ -f '/mnt/cstimer/crt.pem' && -f '/mnt/cstimer/key.pem' ]] || {
    openssl req -nodes -x509 -newkey rsa:4096 \
            -subj "/CN=localhost" \
            -keyout /mnt/cstimer/key.pem \
            -out /mnt/cstimer/crt.pem \
            -sha256 -days 365
}
ln -s /mnt/cstimer/crt.pem /etc/ssl/certs/ssl-cert-snakeoil.pem
ln -s /mnt/cstimer/key.pem /etc/ssl/private/ssl-cert-snakeoil.key

# Start Apache HTTP server
exec apache2-foreground -c 'ServerName localhost' -c 'DirectoryIndex index.php timer.php'

5. Building and running:

To start serving development uncompressed version of csTimer submit following command:

$ ./serve.sh

To build production version of csTimer invoke:

$ ./make.sh clean all

To rebuild only changes invoke without clean target:

$ ./make.sh all

To start serving production version of csTimer submit following command:

$ ./serve.sh prod

After server is launched csTimer will be available on http://localhost:8080/ or https://localhost:8443/ URLs.

In case you want to enable debug logging, add debug=true URL parameter: https://localhost:8443/?debug=true

6. Providing own SSL certificate:

In case you able to create trusted SSL certificate for your local server, you can put crt.pem and key.pem files to the repo root directory. Otherwise self-signed SSL certificates for localhost will be automatically generated by entrypoint script. In some cases it is not possible to use self-signed SSL certificates, for example when accessing development server from mobile devices. In such case either provide trusted by your device SSL certificate, or use ingress service like ngrok.

7. Running development version without Docker:

If you have PHP CLI and optionally ngrok agent installed right on your host system, you can run development version of csTimer without using Docker containers. Just run PHP built-in web server from repo root directory:

$ php -S 0.0.0.0:8080 -t ./src/

After you can access csTimer using insecure HTTP URL - http://localhost:8080/

In case you need to use secured HTTPS connection, install and configure ngrok agent. After ngrok is configured, start secured ingress to forward requests to your local PHP built-in web-server:

$ ngrok http 8080