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 large scaling. To execute the production build, using the docker-compose.prod.yml as follows:

Listing 2: Docker command for production build

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

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

The docker composes the build in 2 stages. First, the Vue application is generated into static files which complies the code into its minimalist state. Secondly, these files are then served over flask using gunicon. After completion, the application can be found on http://localhost:5000. If the port does not suit your needs you can simply change the external port located in the docker-compose.prod.yml file.

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.yml file as follows:

Listing 3: Docker command for development build

$ docker-compose up --build

Frontend: http://localhost:8080/

Backend: http://localhost:5000/api/

It is important to note the development build is depending on ports. Since the backend is run on a different thread then the frontend, API on the frontend must be redirected to a different URL. Adjust of these ports must be done both within the docker-compose.yml and client/vue.config.js under devServer options.

Stopping Container

The Docker container can be stopped by navigating to the applications directory and executing the command shown in the listing below. The process is independent of which build is currently running.

Listing 4: Docker command for stopping container

$ docker-compose up --build

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 6: Updating the git repository

$ git pull

Listing 7: Updating docker image

$ docker-compose -f docker-compose.prod.yml pull