Merge pull request #475 from oist/update-installation-docs

Update optinist install documents.
oist · Apr 24, 2023 · 6bfe14a · 6bfe14a
2 parents 58fe461 + 5d6a47c
commit 6bfe14a
Show file tree

Hide file tree

Showing 10 changed files with 163 additions and 233 deletions.
diff --git a/docs/index.rst b/docs/index.rst
@@ -4,7 +4,7 @@
   contain the root `toctree` directive.
 
 OptiNiSt - Calcium Imaging Pipeline Tool
-===================================
+==========================================
 
 **OptiNiSt(Optical Neuroimage Studio)** helps researchers try multiple data analysis methods, visualize the results, and construct the data analysis pipelines easily and quickly. OptiNiSt's data-saving format follows NWB standards.
 

diff --git a/docs/installation/docker_for_developer.md b/docs/installation/docker_for_developer.md
@@ -1,4 +1,4 @@
-Docker for Developer (recommended)
+Docker for Developer
 =================
 
 ```{contents}

diff --git a/docs/installation/linux_for_developer.md → ...tallation/each_platforms_for_developer.md b/docs/installation/linux_for_developer.md → ...tallation/each_platforms_for_developer.md
@@ -1,4 +1,4 @@
-Linux for Developer (recommended)
+Each Platforms for Developer
 =================
 
 ```{contents}
@@ -15,9 +15,15 @@ Please follow instructions below.
 
 ### Install Tools
 
-#### Install Anaconda
-
-Install [Anaconda for Windows](https://www.anaconda.com/products/individual)
+- Unix-like platforms
+  - Linux
+    - [Install Tools](linux.md#install-tools)
+  - Windows WSL
+    - [Install Tools](windows.md#install-tools-1)
+  - Mac
+    - [Install Tools](mac.md#install-tools)
+- Windows
+    - [Install Tools](windows.md#install-tools)
 
 ### Clone repository
 
@@ -29,8 +35,12 @@ cd ./optinist
 ### Create anaconda environment
 
 ```
-conda create -n optinist python=3.8
-conda activate optinist
+conda create -n optinist_dev python=3.8
+conda activate optinist_dev
+```
+
+```
+conda config --set channel_priority strict
 ```
 
 ### Install requirements
@@ -42,12 +52,12 @@ pip install -r requirements.txt
 ### Set saving directory
 
 Optinist default saving directory is `/tmp/optinist`. If you reboot your PC, this repogitory content is deleted. And setting the saving directory in environment path.
-```bash
+```
 export OPTINIST_DIR="your_saving_dir"
 ```
 
 <!--
-## 2. Create virtualenv
+### 2. Create virtualenv
 
 Under maintenance...
 -->

diff --git a/docs/installation/each_platforms_for_developer_use_mamba.md b/docs/installation/each_platforms_for_developer_use_mamba.md
@@ -0,0 +1,118 @@
+Each Platforms for Developer (Use Mamba)
+=================
+
+```{contents}
+:depth: 4
+```
+
+## Installation
+
+We introduce how to install optinist for developer.
+We have developed optinist python(backend) and typescript(frontend), so you need to make both environment.
+Please follow instructions below.
+
+## 1. Make backend environment
+
+### Install Tools
+
+- Unix-like platforms
+  - Linux
+    - [Install Tools](linux.md#install-tools)
+  - Windows WSL
+    - [Install Tools](windows.md#install-tools-1)
+  - Mac
+    - [Install Tools](mac.md#install-tools)
+- Windows
+  - *Under construction.
+
+#### Install Mamba
+
+- Unix-like platforms
+  - https://mamba.readthedocs.io/en/latest/installation.html
+    - Use Mambaforge
+      - https://github.com/conda-forge/miniforge#mambaforge
+    - Install
+      - for Linux
+        ```
+        curl -L -O "https://github.com/conda-forge/miniforge/releases/latest/download/Mambaforge-$(uname)-$(uname -m).sh"
+        bash Mambaforge-$(uname)-$(uname -m).sh
+
+        # restart shell, and check mamba installed. (show version)
+        mamba --version
+        ```
+      - for Mac (fixed with x86_64)
+        ```
+        curl -L -O "https://github.com/conda-forge/miniforge/releases/latest/download/Mambaforge-$(uname)-x86_64.sh"
+        bash Mambaforge-$(uname)-x86_64.sh
+
+        # restart shell, and check mamba installed. (show version)
+        mamba --version
+        ```
+- Windows
+  - *Under construction.
+
+### Clone repository
+
+```
+git clone https://github.com/oist/optinist.git
+cd ./optinist
+```
+
+### Create mamba(anaconda) environment
+
+<!--
+mamba create -c conda-forge -c bioconda -n optinist_dev python=3.8 snakemake
+-->
+
+```
+mamba create -n optinist_dev python=3.8
+conda activate optinist_dev
+```
+
+```
+conda config --set channel_priority strict
+```
+
+- Note:
+  - If mamba is already installed, snakamake prefers to use mamba over conda.
+
+
+### Install requirements
+
+```
+pip install -r requirements.txt
+```
+
+### Set saving directory
+
+Optinist default saving directory is `/tmp/optinist`. If you reboot your PC, this repogitory content is deleted. And setting the saving directory in environment path.
+```
+export OPTINIST_DIR="your_saving_dir"
+```
+
+<!--
+## 2. Create virtualenv
+
+Under maintenance...
+-->
+
+## 2. Run backend
+
+```
+python main.py
+```
+- `python main.py` log is as blow:
+```
+$ run_optinist
+INFO:     Will watch for changes in these directories: ['/home/oist/optinist/backend']
+INFO:     Uvicorn running on http://0.0.0.0:8000 (Press CTRL+C to quit)
+INFO:     Started reloader process [6520] using statreload
+INFO:     Started server process [6557]
+INFO:     Waiting for application startup.
+INFO:     Application startup complete.
+```
+- Launch browser, and go to http://localhost:8000
+
+It opens correctly!
+
+Done!
diff --git a/docs/installation/index.rst b/docs/installation/index.rst
@@ -16,6 +16,5 @@ Installation
   :caption: Installation (for Developer)
 
   docker_for_developer
-  linux_for_developer
-  windows_for_developer
-  mac_for_developer
+  each_platforms_for_developer
+..  each_platforms_for_developer_use_mamba
diff --git a/docs/installation/linux.md b/docs/installation/linux.md
@@ -11,7 +11,7 @@ We introduce how to install optinist.
 We have developed optinist python(backend) and typescript(frontend), so you need to make both environment.
 Please follow instructions below.
 
-**CAUTION**: We confirmed them on Ubuntu 18.04 or 20.04.
+**CAUTION**: We confirmed them on Ubuntu 18.04/20.04/22.04.
 
 ## 1. Make backend environment
 
@@ -27,8 +27,9 @@ sudo apt install gcc g++
 #### Install Anaconda
 
 ```
-wget https://repo.anaconda.com/archive/Anaconda3-2021.11-Linux-x86_64.sh
-bash Anaconda3-2021.11-Linux-x86_64.sh
+# *The latest version of the module is ok.
+wget https://repo.anaconda.com/archive/Anaconda3-2022.10-Linux-x86_64.sh
+bash Anaconda3-2022.10-Linux-x86_64.sh
 ```
 
 ### Create anaconda environment
@@ -60,7 +61,7 @@ pip install optinist
 ### Set saving directory
 
 Optinist default saving directory is `/tmp/optinist`. If you reboot your PC, this repogitory content is deleted. And setting the saving directory in environment path.
-```bash
+```
 export OPTINIST_DIR="your_saving_dir"
 ```
 

diff --git a/docs/installation/mac.md b/docs/installation/mac.md
@@ -21,11 +21,14 @@ Please follow instructions below.
 
 #### Install Anaconda
 
-Download https://repo.anaconda.com/archive/Anaconda3-2021.11-MacOSX-x86_64.pkg
+- Download and install package.
+  - https://repo.anaconda.com/archive/
+    - Anaconda3-\*.\*-MacOSX-x86_64.pkg
+      - *The latest version of the module is ok.
 
-or Miniconda https://docs.conda.io/en/latest/miniconda.html
-
-Install it.
+- **CAUTION**
+  - On mac, you must use the x86_64 version.
+    - The arm64 version has some modules that cannot be installed by conda install or pip install.
 
 ### Create anaconda environment
 
@@ -47,7 +50,7 @@ pip install optinist
 ### Set saving directory
 
 Optinist default saving directory is `/tmp/optinist`. If you reboot your PC, this repogitory content is deleted. And setting the saving directory in environment path.
-```bash
+```
 export OPTINIST_DIR="your_saving_dir"
 ```
 
@@ -85,10 +88,3 @@ INFO:   Application startup complete.
 It opens correctly!
 
 Done!
-
-
-## FAQ
-
-If you get the warning message shown below, we recommend `rm -rf /Users/usename/opt/anaconda3/envs/optinist ` and recreate conda environment
-or add `--force` option when you create optinist conda environment.
-> WARNING: A directory already exists at the target location '/Users/usename/opt/anaconda3/envs/optinist' but it is not a conda environment.
diff --git a/docs/installation/mac_for_developer.md b/docs/installation/mac_for_developer.md