ExpirySync

This is a repository containing submodules to keep track of API versions and working server and client versions that implement these API versions respectively.

The current API's docs can be found under releases.

Also this repository contains a docker-compose config to bring up a dev environment of server and client.

The license for the complete ExpirySync package is the GPLv3.

Folder structure

expiry_sync_server (git submodule): rails server application handling json requests by the mobile app
expiry_sync_client (git submodule): Ionic app
pm: project management folder containing docs and concepts for both server and client (such as API docs)

Creating issues & contributing

Please only create issues that require changes on both the server and the client (most likely a request for a new feature that requires the server to offer a new service and the client to use this new service).

If that is not the case, please either create the issue on the client's github page (e.g. if it's a usability issue affecting the app only) or on the server's github page (e.g. if it's a database inconsistency bug).

If you want to contribute to this free project, post a comment to the GitHub issue you want to contribute to. (Or if it's a new idea, create a new issue stating that you could implement the request.)

Building app & server with docker

To easily build a working dev environment with server and client using docker, follow those simple steps (Take care: This has only been tested on Linux systems so far):

Install docker-compose and its prerequisites
Clone this repository and run git submodule update --init in the project dir.
Copy env.default to .env and adapt it to your needs.
Bring up all the docker containers with one single command: docker-compose up -d
Now grab some ☕ and wait patiently. (Depending on your internet connection and processor, this might take quite a while!)

To check if everything is up and running you need a way to access the docker instance though your network. On how to do that, you may google, read the docs or - much simpler - just download and use my makeshift script (Simply adds entries to your /etc/hosts file):

# Download the script (One-time setup):
cd /tmp
wget https://gist.github.com/lentschi/63d073467a7c59c1c0dac8c1951341f0/archive/e0386fe7abd5b804ad714cd4735d1bed3332ca3f.zip -O add_docker_host.zip
unzip -j add_docker_host.zip
sudo mv add_docker_host.py /usr/local/bin/add_docker_host
sudo chmod +x /usr/local/bin/add_docker_host

# Repeat everytime after launching the docker
# containers (IPs aren't static by default):
cd /path/to/expiry-sync
./setup/add_docker_hosts_to_etc_hosts.sh
# -> Enter root password when asked to allow modification of /etc/hosts

Congrats - once the docker containers are done working, you should be able to access each part of the app's ecosystem:

API server and web interface: http://expiry-sync-web.local
API server's database (PostgreSQL): psql -h expiry-sync-db.local -U expiry_sync
MailHog (Will catch any mails sent by the server): http://expiry-sync-mail.local
App (in the web version, which - for now - doesn't support all the features the mobile device version provides; only tested browser so far: Google Chrome): http://expiry-sync-app.local

Running in Android emulator

Run docker-compose exec app build-and-run-in-android-emulator to see the app within the android emulator and have it live reload when you change the FE code.

Building the Android app

Here are the instructions to export APKs to ./expiry_sync_client/platforms/android/build/outputs/apk. (On how to transfer them onto a device or emulator, please refer to Google's docs on this topic.)

These examples use wrapper scripts for ionic commands - so, if you know what you're doing, you can of course use those commands directly instead. Note that the scripts may modify config.xml, package.json and package-lock.json so be sure to commit any changes before running them! For the production/release versions, the build process will look for expiry_sync_client/src/environments/environment.prod.ts, which is ingored by git. Copy it from environment.ts and adapt it to your needs (Especially the API server name: defaultServerUrl).

Developer's version

Non-minified debug version with console messages:

docker-compose exec app build-android-dev

Production version

Minified production version without console messages:

docker-compose exec app build-android-prod

Release version

Minified production version without console messages signed for uploading to Google Play.

cp your-android-keystore.keystore ./expiry_sync_client/deploy-keys/expiry-sync.keystore
docker-compose exec app build-android-release

Web version

Minified production version: docker-compose exec app build-web-release. The resulting build will then be exported to ./expiry_sync_client/www and must be hosted through a web server at the root path. (Setting a different base href currently isn't supported, but could easily be implemented if required.)

iOS, Windows, electron

This hasn't been tried yet, but it's possible in theory as the platforms are supported by ionic. It will require some coding though.

Building without docker

Please either see the submodules' READMEs or read the commands/scripts called by docker-compose.yml and adept them to your needs (Therefore you may need some knowledge of docker and SaltStack, which is called by docker-compose).

Testing

To run E2E tests run docker-compose exec app run_e2e_tests. (Note that a first run will take a while as a dummy API server needs to be installed) If you want to debug those tests, connect to expiry-sync-app.local on port 9200. To run the tests in a real Chrome (non-headless), remove the --headless argument from expiry_sync_client/e2e/protractor.conf.js.

For unit testing, see the submodules' READMEs.

lentschi/expiry_sync