TODO Center

This project is a sample prototype to build microservices.

TODO center itself is a central repository for a TODO app which is composed of multiple microservices as follows:

• Todo API Gateway: an API Gateway which proxy frontend requests to individual microservices.
• PHP TODO API: A TODO API service written in PHP.
• Go TODO API: An alternative option for TODO API service written in Go.
• React TODO Web: A TODO Web client based on react.js framework.

TODO center build these services based on Docker, a container management tool by which you can easily setup services and their relations.

Installation

Clone this repository and enter the directory.

git clone https://github.com/scubism/todo_center.git
cd todo_center

Install Docker Engine and Docker Compose on your host machine. For local, you can build a ready-made virtual machine using VirtualBox and Vagrant in the following way.

vagrant up

# For the first time, the following error will occur.
# /sbin/mount.vboxsf: mounting failed with the error: No such device
# Then you should type the following commands for share folder problem.
vagrant plugin install vagrant-vbguest
vagrant vbguest
vagrant reload

# Login to the VM.
vagrant ssh
# Now you are in /vagrant directory (not in /home/vagrant directory).

If you have any further vagrant installation problems, see docs/vagrant-tips.md.

Edit the local configuration if needed.

vi config/config-local.yml

Execute a init file for the first time or config changed.

source init.sh  # execute on every login if you use environmental variables
# Or you can excute it on login automatically by
echo "source init.sh" >> ~/.bashrc

# This will clone and setup dependent microservice repositories
# and create a docker-compose.yml file from config/config.yml and config/config-local.yml.

Build containers based on docker-compose.yml generated by init.sh

docker-compose up -d
# This take several minutes for the first time

Check the container statuses.

docker ps -a

You can access contents via public endpoints for microservices as follows.

# Load config environment
source init.sh

# For TODO API
curl -k https://$config_host:$config_todo_api_gateway_port
# -k option allows connections to SSL sites without certs

# For Web
curl -k https://$config_host:$config_todo_api_gateway_web_port
# Check the url on your browser too.

See docs/docker-tips.md for detail docker operations.

Development

By default, it is not sync for a target source folder between the host and a container. So, in development, you should recreate the container in a development mode which will sync the folder.

# Set container
CONTAINER=php_todo_api

# Remove the previous container for mount change
docker rm -f $CONTAINER

# Start the container with development settings
# the "-f" option specify docker compose setting files which can be overwritten
docker-compose -f docker-compose.yml -f docker-compose-dev.yml up -d $CONTAINER

# Enter the container
docker exec -it $CONTAINER bash

# === Execute any commands ===
...
# Typically you will run your app in background process
./docker-entrypoint.sh &
# Kill the process if needed

Update Todo Center & other repositories

# Run this script
./scripts/update_repos.sh
# Rebuild images if needed
docker-compose up -d --build

Benchmarking

Please read docs/benchmark-with-ab.md for detail.

API Documentation with Swagger

This project use Swagger for documenting backend API. To use it, create your own config-local.yml from config-local.example.yml:

cp ./config/config-local{.example,}.yml

Change compose_mode in config-local.yml to full

# Compose Mode: min|full
#   - min: without swagger_ui & swagger_editor
#   - full: with swagger_ui & swagger_editor
compose_mode: full

Run init.sh to re-generate the docker-compose.yml file:

sh ./init.sh

Start swagger_ui & swagger_editor containers:

docker-compose scale swagger_ui=1 swagger_editor=1

Open these url on your browser:

eval $(./init.sh | grep config_)
echo https://$config_host:$config_swagger_ui_port
echo https://$config_host:$config_swagger_editor_port

• Notice:
  • Make sure to expose swagger.yml somewhere in your api for using swagger_ui, for example "/v1/swagger.yml".
  • Use OpenAPI Specification v2.0 for you swagger.yml file.

License

Released under the MIT License.