diff options
Diffstat (limited to 'README.md')
| -rw-r--r-- | README.md | 134 |
1 files changed, 128 insertions, 6 deletions
@@ -53,6 +53,128 @@ Some of the features of AnnotateChange include: * Time series datasets are verified upon upload acccording to a strict schema. +## Getting Started + +Below are instructions for setting up the application for local development +and for running the application with Docker. + +### Basic + +AnnotateChange can be launched quickly for local development as follows: + +1. Clone the repo + ``` + $ git clone https://github.com/alan-turing-institute/AnnotateChange + $ cd AnnotateChange + ``` + +2. Set up a virtual environment and install dependencies (requires Python + 3.7+) + ``` + $ python -m venv ./venv + $ source ./venv/bin/activate + $ pip install -r requirements.txt + ``` + +3. Create local development environment file + ``` + $ cp .env.example .env.development + ``` + edit this file with ``DB_TYPE=sqlite3`` so we don't have to deal with MySQL + locally. + +4. Initialize the database (this will be a local ``app.db`` file). + ``` + $ ./flask.sh db upgrade + ``` + +5. Create the admin user account + ``` + $ ./flask.sh admin add --auto-confirm-email + ``` + The ``--auto-confirm-email`` flag automatically marks the email address of + the admin user as confirmed. This is mostly useful in development + environments when you don't have a mail address set up yet. + +6. Run the application + ``` + $ ./flask.sh run + ``` + This should tell you where its running, probably ``localhost:5000``. You + should be able to log in with the admin account you've just created. + +7. As admin, upload all demo datasets (included in [demo_data](./demo_data)) + through: Admin Panel -> Add dataset. You should then be able to follow the + introduction to the app (available from the landing page). + +### Docker + +To use AnnotateChange locally using Docker, follow the steps below. For a +full-fledged installation on a server, see the [deployment +instructions](./docs/DEPLOYMENT). + +0. Install [docker](https://docs.docker.com/get-docker/) and + [docker-compose](https://docs.docker.com/compose/install/). + +1. Clone this repository and switch to it: + ``` + $ git clone https://github.com/alan-turing-institute/AnnotateChange + $ cd AnnotateChange + ``` + +2. Build the docker image: + ``` + $ docker build -t gjjvdburg/annotatechange . + ``` + +3. Create the directory for persistent MySQL database storage: + ``` + $ mkdir -p persist/{instance,mysql} + $ sudo chown :1024 persist/instance + $ chmod 775 persist/instance + $ chmod g+s persist/instance + ``` + +4. Copy the environment variables file and adjust where needed + ``` + $ cp .env.example .env + ``` + When moving to production, you'll need to change the `FLASK_ENV` variable + accordingly. Please also make sure to set a proper `SECRET_KEY` and + `AC_MYSQL_PASSWORD` (`= MYSQL_PASSWORD`). You'll also need to configure a + mail account so the application can send out emails for registration etc. + This is what the variables prefixed with ``MAIL_`` are for. The + ``ADMIN_EMAIL`` is likely your own email, it is used when the app + encounters an error and to send backups of the annotation records. You can + limit the email domains users can use with the ``USER_EMAIL_DOMAINS`` + variable. See the [config.py](config.py) file for more info on the + configuration options. + +5. Create a local docker network for communiation between the AnnotateChange + app and the MySQL server: + ``` + $ docker network create web + ``` + +6. Launch the services with docker-compose + ``` + $ docker-compose up + ``` + If all goes well, you should be able to point your browser to + ``localhost:7831`` and see the landing page of the application. Stop the + service before continuing to the next step (by pressing `Ctrl+C`). + +7. Once you have the app running, you'll want to create an admin account so + you can upload datasets, manage tasks and users, and download annotation + results. This can be done using the following command: + ``` + $ docker-compose run --entrypoint 'flask admin add --auto-confirm-email' annotatechange + ``` + +8. As admin, upload all demo datasets (included in [demo_data](./demo_data)) + through: Admin Panel -> Add dataset. You should then be able to follow the + introduction to the app (available from the landing page). + ## Notes This codebase is provided "as is". If you find any problems, please raise an @@ -72,8 +194,7 @@ Below are some thoughts that may help make sense of the codebase. excellent tutorial](https://blog.miguelgrinberg.com/post/the-flask-mega-tutorial-part-i-hello-world) for an introduction to Flask. The [flask.sh](./flask.sh) shell script loads - the appropriate environment variables and runs the application in a virtual - environment managed by Poetry. + the appropriate environment variables and runs the application. * The application handles user management and is centered around the idea of a "task" which links a particular user to a particular time series to @@ -81,10 +202,13 @@ Below are some thoughts that may help make sense of the codebase. * An admin role is available, and the admin user can manually assign and delete tasks as well as add/delete users, datasets, etc. The admin user is - created using the [cli](./app/cli.py). + created using the [cli](./app/cli.py) (see the Getting Started documentation + above). * All datasets must adhere to a specific dataset schema (see - [utils/dataset_schema.json](app/utils/dataset_schema.json)). + [utils/dataset_schema.json](app/utils/dataset_schema.json)). See the files + in [demo_data] for examples, as well as those in + [TCPD](https://github.com/alan-turing-institute/TCPD). * Annotations are stored in the database using 0-based indexing. Tasks are assigned on the fly when a user requests a time series to annotate (see @@ -96,8 +220,6 @@ Below are some thoughts that may help make sense of the codebase. * Configuration of the app is done through environment variables, see the [.env.example](.env.example) file for an example. -* [Poetry](https://python-poetry.org/) is used for dependency management. - * Docker is used for deployment (see the deployment documentation in [docs](docs)), and [Traefik](https://containo.us/traefik/) is used for SSL, etc. |