Getting Started

Contents

• Prerequisites
• Downloading
• Installing with Docker
  • Production Build
  • Development Build
  • Windows Users
  • Database Volume
  • Creating Data Backups
• Updating

Prerequisites

Docker and docker-compose makes it easier to create, deploy and run applications. By shipping the required packages and libraries in Docker containers, the worry for compatibility becomes obsolete. As such, COCO Annotator provides a production and development build. In order to use theses builds Docker and docker-compose is required. You can follow their documentation for installation in the links referenced.

Currently, Docker is the only supported method for installation. If an alternative method is required, the Dockerfiles can act as a break-down for the required environment.

Downloading

The latest version can be downloaded from GitHub or by executing the commands shown in the listing below.

Listing 1: Download COCO Annotator via command line

$ git clone https://github.com/jsbroks/coco-annotator
$ cd coco-annotator

Installing with Docker

It is recommend to run the production build as it is designed for stability and scaling. Also note the development build is dependent on ports and can break API calls if they are changed without the proper adjustments.

Production Build

Production build is the most stable and suitable for supporting a large user base. To execute the production build as follows:

Listing 2: Docker command for production build

$ docker-compose up

This command will pull the latest stable image from dockerhub, which pre-complied with all dependencies. The instance can be found at http://localhost:5000/.

More information can be found in the Implementation Section.

Development Build

Development build provides hot reloading and serves the frontend and backend on two different ports. To execute the development build, using the docker-compose.dev.yml file as follows:

Listing 3: Docker command for development build

$ docker-compose -f docker-compose.dev.yml up --build

Using -f to specify the docker compose file and --build to build the project.

The frontend instance can be found at http://localhost:5000/ and backend at http://localhost:5000/api/.

More information can be found in the Implementation Section.

Stopping Container

The docker container can be stopped by navigating to the applications directory and executing the command shown in the listing below.

Listing 4: Docker command for stopping container

$ docker-compose down

The process is independent of which build is currently running.

Windows

Due to limitations of CIFS implementation in Linux kernel, file change events in mounted folders of a host are not propagated to a container by Docker for Windows (source). You can install docker-windows-volume-watcher or move the images into the datasets directory from within the container as shown below.

Moving Images within a Container

1. Create an image folder inside the datasets directory called temp. Note this will map the directory inside the container to /data/datasets/temp.
2. Place folders or images inside this folder (using windows folder explorer)
3. Create an interactive bash shell on the container (annotator must be running).

$ docker exec -it annotator_flask bash

4. Move the folders or images into the proper datasets folder from within the interactive bash shell terminal

$ mv /data/datasets/temp/some_image_folder /data/dataset/SomeDataset/

Database Volume

The Docker builds uses a volume to store data generated by the database. Although the use of volumes may be confusing for a user not familiar with docker, it provides many advantages over folder mounts.

• Migration and creating backups are easier
• Volumes are compatible with both Linux and Windows containers
• Allows for multiple instances of the application to use the same data

If a user would like to re-install COCO Annotator the task becomes more complicated since the data from the database will be carried from container to container. If you simply delete the application's folder annotations, categories and datasets will still carry over to the new installation. In order to fully remove the database such that all database entries are deleted a user can remove the Docker volume using the command shown below. It is important the Docker container is not running well executing this command.

Listing 5: Docker command for removing volume

$ docker volume rm --force cocoannotator_mongodb_data

Creating Data Backups

Creating backups of your datasets is always recommend for many reasons. In order to successfully backup all data create by this annotation tool, it will require completion in two parts. First, the user can create a copy of the /datasets/ directory found at the root of the project. To backup a data volume you can run a new container using the volume you want to backup and executing the tar command to produce an archive of the volume content as described in the docker user guide.

Updating

Before updating, ensure the container has stopped running.

Listing 7: Updating docker image

$ docker-compose pull

The docker image containers all of the docker files and does not require the repository to be updated. If you would like to update the files as well use:

Listing 6: Updating the git repository

$ git pull