Merge pull request #55 from cvpaperchallenge/develop

feat: merge develop branch into master

README.md

@@ -21,11 +21,11 @@ Please check [the slide format resources about Ascender (Japanese)](https://cvpa
 ## Project Organization
 
 ```
-    ├── .github/           <- Settings for github.
+    ├── .github/           <- Settings for GitHub.
     │
     ├── data/              <- Datasets.
     │
-    ├── environmtns/       <- Provision depends on environments.
+    ├── environments/       <- Provision depends on environments.
     │
     ├── models/            <- Pretrained and serialized models.
     │
@@ -37,12 +37,14 @@ Please check [the slide format resources about Ascender (Japanese)](https://cvpa
     │
     ├── tests/             <- Test codes.
     │
+    ├── .flake8            <- Setting file for Flake8.
     ├── .dockerignore
     ├── .gitignore
     ├── LICENSE
     ├── Makefile           <- Makefile used as task runner. 
-    ├── poetry.lock        <- Lock file. DON'T edit this file manually.  
-    ├── pyproject.toml     <- Setting file.
+    ├── poetry.lock        <- Lock file. DON'T edit this file manually.
+    ├── poetry.toml        <- Setting file for Poetry.
+    ├── pyproject.toml     <- Setting file for Project. (Poetry, Black, isort, Mypy)
     └── README.md          <- The top-level README for developers.
 
 ```
@@ -144,6 +146,26 @@ $ sudo dokcer compose stop
 
 ## FAQ
 
+### Use Ascender without Docker
+
+We recommend using Ascender with Docker as described above. However, you might not be able to install Docker in your development environment due to permission issues or etc.
+
+In such cases, Ascender can be used without Docker. To do that, please install Poetry in your computer, and follow the steps describing in "Start development" section with ignoring the steps related to Docker.
+
+```bash
+# Install Poetry
+$ pip3 install poetry
+
+# Clone repo
+$ git clone [email protected]:<YOUR_USER_NAME>/<YOUR_REPO_NAME>.git
+$ cd <YOUR_REPO_NAME>
+
+# Create virtual environment and install dependent packages by Poetry
+$ poetry install
+```
+
+NOTE: CI job (GitHub Actions workflow) of Ascender is using Dockerfile. Therefore, using Ascender without Docker might raise error at CI job. In that case, please modify the Dockerfile appropriately or delete the CI job (`.github/workflows/lint-and-test.yaml`).
+
 ### Permission error is raised when execute `poetry install`.
 
 Sometime `poetry install` might rise permission error like following:
@@ -162,4 +184,24 @@ $ id -u $USER  # check UID
 $ id -g $USER  # check GID
 ```
 
-In Ascender, default value of both is `1000`. If UID or GID of your local PC is not `1000`, you need to modify the value of `UID` or `GID` inside of `docker-compose.yaml` to align your local PC (please edit their values from `1000`).
+In Ascender, default value of both is `1000`. If UID or GID of your local PC is not `1000`, you need to modify the value of `UID` or `GID` inside of `docker-compose.yaml` to align your local PC (please edit their values from `1000`). Or if environmental variables `HOST_UID` and `HOST_GID` is defined at host PC, Ascender uses these values.
+
+### Compatibility issue between PyTorch and Poetry
+
+NOTE: Now poetry 1.2 is used in Ascender. So this issue is expected to be solved.
+
+Currently, there is a compatibility issue between PyTorch and Poetry. This issue is being worked on by the Poetry community and is expected to be resolved in 1.2.0. (You can check pre-release of 1.2.0 from [here](https://github.com/python-poetry/poetry/releases/tag/1.2.0b3).) 
+
+We plan to incorporate Poetry 1.2.0 into Ascender immediately after its release. In the meantime, please consider using the workaround described in [this issue](https://github.com/python-poetry/poetry/issues/4231).
+
+**Some related GitHub issues**
+- https://github.com/python-poetry/poetry/issues/2339
+- https://github.com/python-poetry/poetry/issues/2543
+- https://github.com/python-poetry/poetry/issues/2613
+- https://github.com/python-poetry/poetry/issues/3855
+- https://github.com/python-poetry/poetry/issues/4231
+- https://github.com/python-poetry/poetry/issues/4704
+
+### Change the Python version to run CI jobs
+
+By default, CI job (GitHub Actions workflow) of Ascender is run against Python 3.8 and 3.9. If you want to change the target Python version, please modify [the matrix part of `.github/workflows/lint-and-test.yaml`](https://github.com/cvpaperchallenge/Ascender/blob/master/.github/workflows/lint-and-test.yaml#L18).

environments/Dockerfile

@@ -26,13 +26,14 @@ RUN apt update && apt install --no-install-recommends -y \
 # For detail, please check following link https://unix.stackexchange.com/questions/410579/change-the-python3-default-version-in-ubuntu
 RUN update-alternatives --install /usr/bin/python3 python3 /usr/bin/python${PYTHON_VERSION} 1 \
     && update-alternatives --set python3 /usr/bin/python${PYTHON_VERSION} \
-    && pip3 install poetry
+    # `requests` needs to be upgraded to avoid RequestsDependencyWarning
+    # ref: https://stackoverflow.com/questions/56155627/requestsdependencywarning-urllib3-1-25-2-or-chardet-3-0-4-doesnt-match-a-s
+    && python3 -m pip install --upgrade pip setuptools requests \
+    && python3 -m pip install --pre poetry
 
 # Add user. Without this, following process is executed as admin. 
 RUN groupadd -g ${GID} ${GROUP_NAME} \
     && useradd -ms /bin/sh -u ${UID} -g ${GID} ${USER_NAME}
 USER ${USER_NAME}
 
 WORKDIR ${APPLICATION_DIRECTORY}
-# Create virtual environments inside of project.
-RUN poetry config virtualenvs.in-project true

environments/cpu/docker-compose.yaml

@@ -6,8 +6,8 @@ services:
       args:
         - BASE_IMAGE=ubuntu:20.04
         - PYTHON_VERSION=3.8
-        - UID=1000
-        - GID=1000
+        - UID=${HOST_UID-1000}
+        - GID=${HOST_GID-1000}
       context: ../../
       dockerfile: environments/Dockerfile
     tty: true

environments/gpu/docker-compose.yaml

@@ -9,8 +9,8 @@ services:
       args:
         - BASE_IMAGE=nvidia/cuda:11.0.3-devel-ubuntu20.04
         - PYTHON_VERSION=3.8
-        - UID=1000
-        - GID=1000
+        - UID=${HOST_UID-1000}
+        - GID=${HOST_GID-1000}
       context: ../../
       dockerfile: environments/Dockerfile
     tty: true

poetry.toml

@@ -0,0 +1,2 @@
+[virtualenvs]
+in-project = true