From b912323ed5d9c75e7d7febec029fcd88d88c55b7 Mon Sep 17 00:00:00 2001 From: Hironsan Date: Tue, 22 Feb 2022 11:32:04 +0900 Subject: [PATCH] Update installation guide --- docs/getting-started.md | 129 ---------------- docs/install-and-upgrade-doccano.md | 224 ++++++++++++++++++++++++++++ docs/mkdocs.yml | 4 +- 3 files changed, 225 insertions(+), 132 deletions(-) delete mode 100644 docs/getting-started.md create mode 100644 docs/install-and-upgrade-doccano.md diff --git a/docs/getting-started.md b/docs/getting-started.md deleted file mode 100644 index 61e8e2d1..00000000 --- a/docs/getting-started.md +++ /dev/null @@ -1,129 +0,0 @@ -# Getting started - -## Usage - -doccano has two options to run: - -- (Recommended) Docker Compose -- Docker - -The usage of docker compose version is explained in the [README.md](https://github.com/doccano/doccano/blob/master/README.md#usage). We highly recommend that you should use docker compose version. However, we explain the usage of Docker version and Python/Node version for the additional information. - -### Docker - -As a one-time setup, create a Docker container for Doccano: - -```bash -docker pull doccano/doccano -docker container create --name doccano \ - -e "ADMIN_USERNAME=admin" \ - -e "ADMIN_EMAIL=admin@example.com" \ - -e "ADMIN_PASSWORD=password" \ - -p 8000:8000 doccano/doccano -``` - -Next, start Doccano by running the container: - -```bash -docker container start doccano -``` - -To stop the container, run `docker container stop doccano -t 5`. -All data created in the container will persist across restarts. - -Go to . - -### Setup development environment - -You can setup development environment via Python and Node.js. You need to install Git and to clone the repository: - -```bash -git clone https://github.com/doccano/doccano.git -cd doccano -``` - -### Backend - -The doccano backend is built in Python 3.8+ and uses [Poetry](https://github.com/python-poetry/poetry) as a dependency manager. If you haven't installed them yet, please see [Python](https://www.python.org/downloads/) and [Poetry](https://python-poetry.org/docs/) documentation. - -First, to install the defined dependencies for our project, just run the `install` command. After that, activate the virtual environment by runnning `shell` command: - -```bash -cd backend -poetry install -poetry shell -``` - -Second, setup database and run the development server. Doccano uses [Django](https://www.djangoproject.com/) and [Django Rest Framework](https://www.django-rest-framework.org/) as a backend. We can setup them by using Django command: - -```bash -python manage.py migrate -python manage.py create_roles -python manage.py create_admin --noinput --username "admin" --email "admin@example.com" --password "password" -python manage.py runserver -``` - -In another terminal, you need to run Celery to use import/export dataset feature: - -```bash -cd doccano/backend -celery --app=config worker --loglevel=INFO --concurrency=1 -``` - -After you change the code, don't forget to run [mypy](https://mypy.readthedocs.io/en/stable/index.html), [flake8](https://flake8.pycqa.org/en/latest/), [black](https://github.com/psf/black), and [isort](https://github.com/PyCQA/isort). These ensures the code consistency. To run them, just run the following commands: - -```bash -poetry run task mypy -poetry run task flake8 -poetry run task black -poetry run task isort -``` - -Similarly, you can run the test by executing the following command: - -```bash -poetry run task test -``` - -Did you pass the test? Great! - -### Frontend - -The doccano frontend is built in Node.js and uses [Yarn](https://yarnpkg.com/) as a package manager. If you haven't installed them yet, please see [Node.js](https://nodejs.org/en/) and [Yarn](https://yarnpkg.com/) documentation. - -First, to install the defined dependencies for our project, just run the `install` command. - -```bash -cd frontend -yarn install -``` - -Then run the `dev` command to serve with hot reload at : - -```bash -yarn dev -``` - -## How to create a Python package - -During development, you may want to create a Python package and verify it works correctly. In such a case, you can create a package by running the following command in the root directory of your project: - -```bash -./tools/create-package.sh -``` - -This command builds the frontend, copies the files, and packages them. This will take a few minutes. After finishing the command, you will find `sdist` and `wheel` in `backend/dist`: - -```bash -Building doccano (1.5.5.post335.dev0+6be6d198) - - Building sdist - - Built doccano-1.5.5.post335.dev0+6be6d198.tar.gz - - Building wheel - - Built doccano-1.5.5.post335.dev0+6be6d198-py3-none-any.whl -``` - -Then, you can install the package via `pip install` command: - -```bash -pip install doccano-1.5.5.post335.dev0+6be6d198-py3-none-any.whl -``` diff --git a/docs/install-and-upgrade-doccano.md b/docs/install-and-upgrade-doccano.md new file mode 100644 index 00000000..f0b298ec --- /dev/null +++ b/docs/install-and-upgrade-doccano.md @@ -0,0 +1,224 @@ +# Install doccano + +Install doccano on local or in the cloud. Choose the installation method that works best for your environment: + +- [Install with pip](#install-with-pip) +- [Install with Docker](#install-with-docker) +- [Install with Docker Compose](#install-with-docker-compose) +- [Install from source](#install-from-source) +- [Install to cloud](#install-to-cloud) +- [Upgrade doccano](#upgrade-doccano) + +## System requirements + +You can install doccano on a Linux, Windows, or macOS machine running Python 3.8+. + +### Web browser support + +doccano is tested with the latest version of Google Chrome and is expected to work in the latest versions of: + +- Google Chrome +- Apple Safari + +If using other web browsers, or older versions of supported web browsers, unexpected behavior could occur. + +### Port requirements + +doccano uses port 8000 by default. To use a different port, specify it when running doccano webserver. + +## Install with pip + +To install doccano with pip, you need Python 3.8+. Run the following: + +```bash +pip install doccano +``` + +After you install doccano, start the server with the following command: + +```bash +# Initialize database. First time only. +doccano init +# Create a super user. First time only. +doccano createuser --username admin --password pass +# Start a web server. +doccano webserver --port 8000 +``` + +In another terminal, run the following command: + +```bash +# Start the task queue to handle file upload/download. +doccano task +``` + +Open . + +## Install with Docker + +doccano is also available as a [Docker](https://www.docker.com/) container. Make sure you have Docker installed on your machine. + +To install and start doccano at , run the following command: + +```bash +docker pull doccano/doccano +docker container create --name doccano \ + -e "ADMIN_USERNAME=admin" \ + -e "ADMIN_EMAIL=admin@example.com" \ + -e "ADMIN_PASSWORD=password" \ + -p 8000:8000 doccano/doccano +``` + +Next, start doccano by running the container: + +```bash +docker container start doccano +``` + +To stop the container, run `docker container stop doccano -t 5`. +All data created in the container persist across restarts. + +### Build a local image with Docker + +If you want to build a local image, run: + +```bash +docker build -t doccano:latest . -f docker/Dockerfile +``` + +## Install with Docker Compose + +You need to install Git and to clone the repository: + +```bash +git clone https://github.com/doccano/doccano.git +cd doccano +``` + +To install and start doccano at , run the following command: + +```bash +docker-compose -f docker/docker-compose.prod.yml --env-file ./docker/.env.example up +``` + +You can override the default setting by rewriting the `.env` file. + +## Install from source + +If you want to develop doccano, consider downloading the source code using Git and running doccano locally. First of all, clone the repository: + +```bash +git clone https://github.com/doccano/doccano.git +cd doccano +``` + +### Backend + +The doccano backend is built in Python 3.8+ and uses [Poetry](https://github.com/python-poetry/poetry) as a dependency manager. If you haven't installed them yet, please see [Python](https://www.python.org/downloads/) and [Poetry](https://python-poetry.org/docs/) documentation. + +First, to install the defined dependencies for our project, just run the `install` command. After that, activate the virtual environment by running `shell` command: + +```bash +cd backend +poetry install +poetry shell +``` + +Second, set up the database and run the development server. Doccano uses [Django](https://www.djangoproject.com/) and [Django Rest Framework](https://www.django-rest-framework.org/) as a backend. We can set up them by using Django command: + +```bash +python manage.py migrate +python manage.py create_roles +python manage.py create_admin --noinput --username "admin" --email "admin@example.com" --password "password" +python manage.py runserver +``` + +In another terminal, you need to run Celery to use import/export dataset feature: + +```bash +cd doccano/backend +celery --app=config worker --loglevel=INFO --concurrency=1 +``` + +After you change the code, don't forget to run [mypy](https://mypy.readthedocs.io/en/stable/index.html), [flake8](https://flake8.pycqa.org/en/latest/), [black](https://github.com/psf/black), and [isort](https://github.com/PyCQA/isort). These ensure code consistency. To run them, just run the following commands: + +```bash +poetry run task mypy +poetry run task flake8 +poetry run task black +poetry run task isort +``` + +Similarly, you can run the test by executing the following command: + +```bash +poetry run task test +``` + +Did you pass the test? Great! + +### Frontend + +The doccano frontend is built in Node.js and uses [Yarn](https://yarnpkg.com/) as a package manager. If you haven't installed them yet, please see [Node.js](https://nodejs.org/en/) and [Yarn](https://yarnpkg.com/) documentation. + +First, to install the defined dependencies for our project, just run the `install` command. + +```bash +cd frontend +yarn install +``` + +Then run the `dev` command to serve with hot reload at : + +```bash +yarn dev +``` + +### How to create a Python package + +During development, you may want to create a Python package and verify it works correctly. In such a case, you can create a package by running the following command in the root directory of your project: + +```bash +./tools/create-package.sh +``` + +This command builds the frontend, copies the files, and packages them. This will take a few minutes. After finishing the command, you will find `sdist` and `wheel` in `backend/dist`: + +```bash +Building doccano (1.5.5.post335.dev0+6be6d198) + - Building sdist + - Built doccano-1.5.5.post335.dev0+6be6d198.tar.gz + - Building wheel + - Built doccano-1.5.5.post335.dev0+6be6d198-py3-none-any.whl +``` + +Then, you can install the package via `pip install` command: + +```bash +pip install doccano-1.5.5.post335.dev0+6be6d198-py3-none-any.whl +``` + +## Install to cloud + +doccano also supports one-click deployment to cloud providers. Click the following button, configure the environment, and access the UI. + +| Service | Button | +|---------|---| +| AWS | [![AWS CloudFormation Launch Stack SVG Button](https://cdn.rawgit.com/buildkite/cloudformation-launch-stack-button-svg/master/launch-stack.svg)](https://console.aws.amazon.com/cloudformation/home?#/stacks/new?stackName=doccano&templateURL=https://doccano.s3.amazonaws.com/public/cloudformation/template.aws.yaml) | +| Heroku | [![Deploy](https://www.herokucdn.com/deploy/button.svg)](https://dashboard.heroku.com/new?template=https%3A%2F%2Fgithub.com%2Fdoccano%2Fdoccano) | + +## Upgrade doccano + +Caution: If you use SQLite3 as a database, upgrading the package would lose your database. + +To upgrade to the latest version of doccano, reinstall or upgrade using pip. + +```bash +pip install -U doccano +``` + +If you need update the database scheme, run the following: + +```bash +doccano migrate +``` diff --git a/docs/mkdocs.yml b/docs/mkdocs.yml index 49dd600b..679638bb 100644 --- a/docs/mkdocs.yml +++ b/docs/mkdocs.yml @@ -32,14 +32,12 @@ plugins: # Page tree nav: - Get started: index.md - - Installation: getting-started.md + - Install and upgrade doccano: install-and-upgrade-doccano.md - Tutorial: tutorial.md - Project Structure: project_structure.md - Advanced: - AWS HTTPS settings: advanced/aws_https_settings.md - OAuth2 settings: advanced/oauth2_settings.md - #- Release notes: release-notes.md - #- Author's notes: authors-notes.md - FAQ: faq.md - Code of Conduct: CODE_OF_CONDUCT.md - Roadmap: roadmap.md