mirror of https://github.com/doccano/doccano.git
Hironsan
5 years ago
7 changed files with 402 additions and 9 deletions
Split View
Diff Options
-
100docs/advanced/aws_https_settings.md
-
36docs/advanced/oauth2_settings.md
-
55docs/faq.md
-
102docs/getting-started.md
-
59docs/index.md
-
18docs/roadmap.md
-
41mkdocs.yml
@ -0,0 +1,100 @@ |
|||
# HTTPS settings for doccano in AWS |
|||
|
|||
|
|||
1. Create hosted zone in Route 53 |
|||
2. Create certificate in ACM |
|||
3. Create EC2 instance |
|||
4. Create ELB |
|||
5. Create A record in Route 53 |
|||
|
|||
|
|||
|
|||
# Create hosted zone in Route 53 |
|||
|
|||
HTTPS need a domain name. If you don't have one, you can register it by the AWS Route 53 service, or you can get one from other domain seller. |
|||
|
|||
After you get a domain name, you can create Hosted Zone by Route 53. |
|||
|
|||
If you register domain from Route 53, you can find it in the `Hosted Zone`. |
|||
|
|||
 |
|||
|
|||
|
|||
|
|||
# Create certificate in ACM |
|||
|
|||
 |
|||
|
|||
You should replace the domain name by yours. |
|||
|
|||
 |
|||
|
|||
|
|||
|
|||
|
|||
|
|||
 |
|||
|
|||
|
|||
|
|||
 |
|||
|
|||
|
|||
|
|||
Don't forget to Create record in Route 53 in step 4. |
|||
|
|||
After you request a certificate, wait for a while, You should see the status become 'Issued'. |
|||
|
|||
|
|||
|
|||
 |
|||
|
|||
# Create EC2 instance |
|||
|
|||
In this part, you can just click the launch button to create a EC2 instance. |
|||
|
|||
[](https://us-east-1.console.aws.amazon.com/cloudformation/home?region=us-east-1#/stacks/create/review?templateURL=https://s3-external-1.amazonaws.com/cf-templates-10vry9l3mp71r-us-east-1/20190732wl-new.templatexloywxxyimi&stackName=doccano) |
|||
|
|||
# Create ELB |
|||
|
|||
 |
|||
|
|||
Click the `Create Load Balancer` button and select `Application Load Balancer`. |
|||
|
|||
Fill the name, change protocol to HTTPS, and do not forget add at least two availability zones. Make sure the zone that EC2 instance created is included. |
|||
|
|||
 |
|||
|
|||
Select the certificate we created early. |
|||
|
|||
 |
|||
|
|||
You can select the same security groups created when you create the EC2 instance. |
|||
|
|||
 |
|||
|
|||
Or you can create a new one |
|||
|
|||
 |
|||
|
|||
|
|||
|
|||
Fill the target group name and leave others defualt. |
|||
|
|||
 |
|||
|
|||
Add the instance to registered. |
|||
|
|||
 |
|||
|
|||
Then review and create. |
|||
|
|||
# Create A record in Route 53 |
|||
|
|||
Back to route 53, and click `Create Record Set`. Fill the subname and the ELB name in the `Alias Target`. |
|||
|
|||
 |
|||
|
|||
Finally, you can access the doccano by HTTPS. |
|||
|
|||
 |
|||
@ -0,0 +1,36 @@ |
|||
This document aims to instruct how to setup OAuth for doccano. doccano now supports social login via GitHub and Active Directory by [#75](https://github.com/chakki-works/doccano/pull/75). In this document, we show GitHub OAuth as an example. |
|||
|
|||
|
|||
## Create OAuth App |
|||
|
|||
1. In the upper-right corner of GitHub, click your profile photo, then click **Settings**. |
|||
2. In the left sidebar, click **Developer settings**. |
|||
3. In the left sidebar, click **OAuth Apps**. |
|||
4. Click **New OAuth App**. |
|||
5. In "Application name", type the name of your app. |
|||
6. In "Homepage URL", type the full URL to your app's website. |
|||
7. In "Authorization callback URL", type the callback URL(e.g. <https://example.com/social/complete/github/>) of your app. |
|||
8. Click Register application. |
|||
|
|||
## Set enviromental variables |
|||
|
|||
Once the application is registered, your app's `Client ID` and `Client Secret` will be displayed on the following page: |
|||
 |
|||
|
|||
1. Copy the `Client ID` and `Client Secret` from the Developer Applications of your app on GitHub. |
|||
2. Set the `Client ID` and `Client Secret` to enviromental variables: |
|||
|
|||
```bash |
|||
export OAUTH_GITHUB_KEY=YOUR_CLIENT_ID |
|||
export OAUTH_GITHUB_SECRET=YOUR_CLIENT_SECRET |
|||
``` |
|||
|
|||
## Run server |
|||
|
|||
```bash |
|||
python manage.py runserver |
|||
``` |
|||
|
|||
Go to login page: |
|||
|
|||
 |
|||
@ -0,0 +1,55 @@ |
|||
## I can't install doccano. |
|||
|
|||
Following list is ordered by from easy to hard. If you are not familiar with Python development, please consider easy setup. |
|||
|
|||
1. [One click deployment to Cloud Service.](https://github.com/chakki-works/doccano#deployment) |
|||
* Only you have to do is create an account. Especially [Heroku](https://www.heroku.com/home) does not require your credit card (if free plan). |
|||
* [](https://portal.azure.com/#create/Microsoft.Template/uri/https%3A%2F%2Fraw.githubusercontent.com%2Fchakki-works%2Fdoccano%2Fmaster%2Fazuredeploy.json) |
|||
* [](https://heroku.com/deploy) |
|||
* [](https://us-east-1.console.aws.amazon.com/cloudformation/home?region=us-east-1#/stacks/create/review?templateURL=https://s3-external-1.amazonaws.com/cf-templates-10vry9l3mp71r-us-east-1/20190732wl-new.templatexloywxxyimi&stackName=doccano) |
|||
* > Notice: (1) EC2 KeyPair cannot be created automatically, so make sure you have an existing EC2 KeyPair in one region. Or [create one yourself](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2-key-pairs.html#having-ec2-create-your-key-pair). (2) If you want to access doccano via HTTPS in AWS, here is an [instruction](https://github.com/chakki-works/doccano/wiki/HTTPS-setting-for-doccano-in-AWS). |
|||
2. [Use Docker](https://docs.docker.com/install/) |
|||
* Docker doesn't bother you by the OS, Python version, etc problems. Because an environment for application is packed as a container. |
|||
* Get doccano's image: `docker pull chakkiworks/doccano` |
|||
* Create & Run doccano container: `docker run -d --name doccano -p 8000:80 chakkiworks/doccano` |
|||
* Create a user: `docker exec doccano tools/create-admin.sh "admin" "admin@example.com" "password"` |
|||
* Stop doccano container: `docker stop doccano` |
|||
* Re-Launch doccano container: `docker start doccano` |
|||
3. Install from source |
|||
* **I want to remember you that this is the hardest setup way. You have to install Python/Node.js and type many commands.** |
|||
* [Install Python](https://www.python.org/downloads/) |
|||
* [Install Node.js](https://nodejs.org/en/download/) |
|||
* Get the source code of doccano: `git clone https://github.com/chakki-works/doccano.git` |
|||
* Move to doccano directory: `cd doccano` |
|||
* Create environment for doccano: `virtualenv venv` |
|||
* Activate environment: `source venv/bin/activate` |
|||
* Install required packages: `pip install -r requirements.txt` |
|||
* Move server directory: `cd app/server` |
|||
* Build frontend library: `npm install` |
|||
* Build frontend source code: `npm run build` |
|||
* Back to server directory: `cd ../` |
|||
* Initialize doccano: `python manage.py migrate` |
|||
* Create user: `python manage.py createsuperuser` |
|||
* Run doccano: `python manage.py runserver` |
|||
* Stop doccano: Ctrl+C |
|||
* Re-Launch doccano: `python manage.py runserver` (Confirm you are at `app/server` directory and environment is active). |
|||
|
|||
## I can't upload my data. |
|||
|
|||
Please check the following list. |
|||
|
|||
- File encoding: `UTF-8` is appropriate. |
|||
- Filename: alphabetic file name is suitable. |
|||
- File format selection: File format radio button should be selected properly. |
|||
- When you are using JSON/JSONL: Confirm JSON data is valid. |
|||
- You can use [JSONLint](https://jsonlint.com/) or some other tool (when JSONL, pick one data and check it). |
|||
- When you are using CSV: Confirm CSV data is valid. |
|||
- You can use Excel or some tools that have import CSV feature. |
|||
- Lack of line: Data file should not contain blank line. |
|||
- Lack of field: Data file should not contain blank field. |
|||
|
|||
**You don't need your real & all data to validate file format. The picked data & masked data is suitable if your data is large or secret.** |
|||
|
|||
## I want to add annotators. |
|||
|
|||
* You can create other annotators by [Django Admin site](https://djangobook.com/django-admin-site/). |
|||
@ -0,0 +1,102 @@ |
|||
# Getting started |
|||
|
|||
## Quick install guide |
|||
|
|||
First of all, you have to clone the repository: |
|||
|
|||
```bash |
|||
git clone https://github.com/chakki-works/doccano.git |
|||
cd doccano |
|||
``` |
|||
|
|||
To install doccano, there are three options: |
|||
|
|||
### Option1: Pull the production Docker image |
|||
|
|||
```bash |
|||
docker pull chakkiworks/doccano |
|||
``` |
|||
|
|||
### Option2: Pull the development Docker-Compose images |
|||
|
|||
```bash |
|||
docker-compose pull |
|||
``` |
|||
|
|||
### Option3: Setup Python environment |
|||
|
|||
First we need to install the dependencies. Run the following commands: |
|||
|
|||
```bash |
|||
pip install -r requirements.txt |
|||
cd app |
|||
``` |
|||
|
|||
Next we need to start the webpack server so that the frontend gets compiled continuously. |
|||
Run the following commands in a new shell: |
|||
|
|||
```bash |
|||
cd server/static |
|||
npm install |
|||
npm run build |
|||
# npm start # for developers |
|||
cd .. |
|||
``` |
|||
|
|||
## Usage |
|||
|
|||
Let’s start the development server and explore it. |
|||
|
|||
Depending on your installation method, there are two options: |
|||
|
|||
### Option1: Running the Docker image as a Container |
|||
|
|||
First, run a Docker container: |
|||
|
|||
```bash |
|||
docker run -d --name doccano -p 8000:80 chakkiworks/doccano |
|||
``` |
|||
|
|||
Then, execute `create-admin.sh` script for creating a superuser. |
|||
|
|||
```bash |
|||
docker exec doccano tools/create-admin.sh "admin" "admin@example.com" "password" |
|||
``` |
|||
|
|||
### Option2: Running the development Docker-Compose stack |
|||
|
|||
We can use docker-compose to set up the webpack server, django server, database, etc. all in one command: |
|||
|
|||
```bash |
|||
docker-compose up |
|||
``` |
|||
|
|||
Now, open a Web browser and go to <http://127.0.0.1:8000/login/>. You should see the login screen: |
|||
|
|||
 |
|||
|
|||
### Option3: Running Django development server |
|||
|
|||
Before running, we need to make migration. Run the following command: |
|||
|
|||
```bash |
|||
python manage.py migrate |
|||
``` |
|||
|
|||
Next we need to create a user who can login to the admin site. Run the following command: |
|||
|
|||
```bash |
|||
python manage.py create_admin --noinput --username "admin" --email "admin@example.com" --password "password" |
|||
``` |
|||
|
|||
Developers can also validate that the project works as expected by running the tests: |
|||
|
|||
```bash |
|||
python manage.py test server.tests |
|||
``` |
|||
|
|||
Finally, to start the server, run the following command: |
|||
|
|||
```bash |
|||
python manage.py runserver |
|||
``` |
|||
@ -0,0 +1,59 @@ |
|||
# Welcome to doccano |
|||
|
|||
## Text Annotation for Human |
|||
|
|||
doccano is an open source text annotation tool for human. It provides annotation features for text classification, sequence labeling and sequence to sequence. So, you can create labeled data for sentiment analysis, named entity recognition, text summarization and so on. Just create project, upload data and start annotation. You can build dataset in hours. |
|||
|
|||
|
|||
## Demo |
|||
|
|||
You can enjoy [annotation demo](http://doccano.herokuapp.com). |
|||
|
|||
### [Named entity recognition](https://doccano.herokuapp.com/demo/named-entity-recognition/) |
|||
|
|||
First demo is one of the sequence labeling tasks, named-entity recognition. You just select text spans and annotate it. Since doccano supports shortcut key, so you can quickly annotate text spans. |
|||
|
|||
 |
|||
|
|||
### [Sentiment analysis](https://doccano.herokuapp.com/demo/text-classification/) |
|||
|
|||
Second demo is one of the text classification tasks, topic classification. Since there may be more than one category, you can annotate multi-labels. |
|||
|
|||
 |
|||
|
|||
### [Machine translation](https://doccano.herokuapp.com/demo/translation/) |
|||
|
|||
Final demo is one of the sequence to sequence tasks, machine translation. Since there may be more than one responses in sequence to sequence tasks, you can create multi responses. |
|||
|
|||
 |
|||
|
|||
## Quick Deployment |
|||
|
|||
### Azure |
|||
|
|||
Doccano can be deployed to Azure ([Web App for Containers](https://azure.microsoft.com/en-us/services/app-service/containers/) + |
|||
[PostgreSQL database](https://azure.microsoft.com/en-us/services/postgresql/)) by clicking on the button below: |
|||
|
|||
[](https://portal.azure.com/#create/Microsoft.Template/uri/https%3A%2F%2Fraw.githubusercontent.com%2Fchakki-works%2Fdoccano%2Fmaster%2Fazuredeploy.json) |
|||
|
|||
### Heroku |
|||
|
|||
Doccano can be deployed to [Heroku](https://www.heroku.com/) by clicking on the button below: |
|||
|
|||
[](https://heroku.com/deploy) |
|||
|
|||
Of course, you can deploy doccano by using [heroku-cli](https://devcenter.heroku.com/articles/heroku-cli). |
|||
|
|||
```bash |
|||
heroku create |
|||
heroku stack:set container |
|||
git push heroku master |
|||
``` |
|||
|
|||
### AWS |
|||
|
|||
Doccano can be deployed to AWS ([Cloudformation](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/Welcome.html)) by clicking on the button below: |
|||
|
|||
[](https://us-east-1.console.aws.amazon.com/cloudformation/home?region=us-east-1#/stacks/create/review?templateURL=https://s3-external-1.amazonaws.com/cf-templates-10vry9l3mp71r-us-east-1/20190732wl-new.templatexloywxxyimi&stackName=doccano) |
|||
|
|||
> Notice: (1) EC2 KeyPair cannot be created automatically, so make sure you have an existing EC2 KeyPair in one region. Or [create one yourself](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2-key-pairs.html#having-ec2-create-your-key-pair). (2) If you want to access doccano via HTTPS in AWS, here is an [instruction](https://github.com/chakki-works/doccano/wiki/HTTPS-setting-for-doccano-in-AWS). |
|||
@ -0,0 +1,41 @@ |
|||
# Project information |
|||
site_name: 'doccano' |
|||
site_description: 'A Text Annotation tool for Human' |
|||
site_author: 'Hiroki Nakayama' |
|||
site_url: 'https://chakki-works.github.io/doccano/' |
|||
|
|||
# Repository |
|||
repo_name: 'chakki-works/doccano' |
|||
repo_url: 'https://github.com/chakki-works/doccano' |
|||
|
|||
# Copyright |
|||
copyright: 'Copyright © 2018 - 2019 Hiroki Nakayama' |
|||
|
|||
theme: |
|||
name: 'material' |
|||
palette: |
|||
primary: 'cyan' |
|||
accent: 'cyan' |
|||
show_sidebar: true |
|||
|
|||
extra: |
|||
social: |
|||
- type: 'github' |
|||
link: 'https://github.com/Hironsan' |
|||
- type: 'twitter' |
|||
link: 'https://twitter.com/Hironsan13' |
|||
|
|||
# Page tree |
|||
nav: |
|||
- Doccano: index.md |
|||
- Getting started: getting-started.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 |
|||
- Contributing: CONTRIBUTING.md |
|||
- Code of Conduct: CODE_OF_CONDUCT.md |
|||
- Roadmap: roadmap.md |
|||
- License: LICENSE.md |
|||
Write
Preview
Loading…
Cancel
Save