docs: extend and correct installation instructions

neherlab · Feb 12, 2025 · c6e3d85 · c6e3d85
1 parent 3690de8
commit c6e3d85
Show file tree

Hide file tree

Showing 5 changed files with 151 additions and 16 deletions.
diff --git a/docs/bun.lockb b/docs/bun.lockb
diff --git a/docs/docs/installation/standalone.md b/docs/docs/installation/standalone.md
@@ -15,18 +15,118 @@ This is the recommended way to install Pangraph
 
 Pangraph CLI is a self-contained single-file executable which can be downloaded and run without any particular setup.
 
+|         | x86_64                                                                                                                                                                                                               | arm64                                                                                                                                                                                                                  |
+|---------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| Linux   | [gnu](https://github.com/neherlab/pangraph/releases/latest/download/pangraph-x86_64-unknown-linux-gnu), [musl](https://github.com/neherlab/pangraph/releases/latest/download/pangraph-x86_64-unknown-linux-musl)[^1] | [gnu](https://github.com/neherlab/pangraph/releases/latest/download/pangraph-aarch64-unknown-linux-gnu), [musl](https://github.com/neherlab/pangraph/releases/latest/download/pangraph-aarch64-unknown-linux-musl)[^1] |
+| macOS   | [download](https://github.com/neherlab/pangraph/releases/latest/download/pangraph-x86_64-apple-darwin)                                                                                                               | [download](https://github.com/neherlab/pangraph/releases/latest/download/pangraph-aarch64-apple-darwin)                                                                                                                |
+| Windows | [download](https://github.com/neherlab/pangraph/releases/latest/download/pangraph-x86_64-pc-windows-gnu.exe)                                                                                                         | -                                                                                                                                                                                                                      |
 
+:::info[Note]
 
-|         | x86_64                                                                                                                                                                                                            | arm64                                                                                                                                                                                                               |
-| ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Linux   | [gnu](https://github.com/neherlab/pangraph/releases/latest/download/pangraph-x86_64-unknown-linux-gnu), [musl](https://github.com/neherlab/pangraph/releases/latest/download/pangraph-x86_64-unknown-linux-musl)* | [gnu](https://github.com/neherlab/pangraph/releases/latest/download/pangraph-aarch64-unknown-linux-gnu), [musl](https://github.com/neherlab/pangraph/releases/latest/download/pangraph-aarch64-unknown-linux-musl)* |
-| macOS   | [download](https://github.com/neherlab/pangraph/releases/latest/download/pangraph-x86_64-apple-darwin)                                                                                                            | [download](https://github.com/neherlab/pangraph/releases/latest/download/pangraph-aarch64-apple-darwin)                                                                                                             |
-| Windows | [download](https://github.com/neherlab/pangraph/releases/latest/download/pangraph-x86_64-pc-windows-gnu.exe)                                                                                                      | -                                                                                                                                                                                                                   |
-## optional dependencies - mmseqs2
+There are 2 flavors of pangraph executables for Linux platforms - "gnu" and "musl". 
 
-When building graphs, in addition to the native _minimap2_, Pangraph can use [_mmseqs2_](https://github.com/soedinglab/MMseqs2) as an alignment kernel.[^1] _mmseqs2_ is able to find homology between sequences with up to around 30% sequence divergence, at the cost of higher computational time.
+The "gnu" flavor is generally faster but requires GNU libc >= 2.17 to be present on the system. Linux distros like Debian, Ubuntu, Red Hat, Fedora, Arch all come with GNU libc by default. 
 
-[^1]: This kernel can be selected with the `-k mmseqs` option when running the [`pangraph build`](../reference.md#pangraph-build) command.
+The "musl" flavor can be slower, but it makes no assumptions about libc. It is suitable for distros like Alpine, which have no GNU libc, or on older distros which have very old GNU libc.
+
+All flavors require Linux kernel >= 3.2.
+
+:::
+
+
+:::info[Note]
+
+On Unix platforms, don't forget to set executable file permission. You probably want to rename the executable and place it into `$PATH` to simplify its usage:
+
+```bash
+# Assuming ${HOME}/bin/pangraph is in $PATH
+mv pangraph-x86_64-unknown-linux-gnu $HOME/bin/pangraph
+chmod +x ${HOME}/bin/pangraph
+pangraph --help
+```
+
+:::
+
+## Installing from command line
+
+You can also download pangraph programmatically, for example to add it to your Docker image or a bioinformatics pipeline:
+
+<Tabs>
+  <TabItem value="linuxX86" label="Linux x86">
+    #### GNU, Latest Version
+    ```bash
+    curl -fsSL "https://github.com/neherlab/pangraph/releases/latest/download/pangraph-x86_64-unknown-linux-gnu" -o "pangraph" && chmod +x pangraph
+    ```
+    #### GNU, Specific Version
+    ```bash
+    curl -fsSL "https://github.com/neherlab/pangraph/releases/download/1.0.0/pangraph-x86_64-unknown-linux-gnu" -o "pangraph" && chmod +x pangraph
+    ```
+    #### MUSL, Latest Version
+    ```bash
+    curl -fsSL "https://github.com/neherlab/pangraph/releases/latest/download/pangraph-x86_64-unknown-linux-musl" -o "pangraph" && chmod +x pangraph
+    ```
+    #### MUSL, Specific Version
+    ```bash
+    curl -fsSL "https://github.com/neherlab/pangraph/releases/download/1.0.0/pangraph-x86_64-unknown-linux-musl" -o "pangraph" && chmod +x pangraph
+    ```
+  </TabItem>
+  <TabItem value="linuxArm64" label="Linux ARM64">
+    #### GNU, Latest Version
+    ```bash
+    curl -fsSL "https://github.com/neherlab/pangraph/releases/latest/download/pangraph-aarch64-unknown-linux-gnu" -o "pangraph" && chmod +x pangraph
+    ```
+    #### GNU, Specific Version
+    ```bash
+    curl -fsSL "https://github.com/neherlab/pangraph/releases/download/1.0.0/pangraph-aarch64-unknown-linux-gnu" -o "pangraph" && chmod +x pangraph
+    ```
+    #### MUSL, Latest Version
+    ```bash
+    curl -fsSL "https://github.com/neherlab/pangraph/releases/latest/download/pangraph-aarch64-unknown-linux-musl" -o "pangraph" && chmod +x pangraph
+    ```
+    #### MUSL, Specific Version
+    ```bash
+    curl -fsSL "https://github.com/neherlab/pangraph/releases/download/1.0.0/pangraph-aarch64-unknown-linux-musl" -o "pangraph" && chmod +x pangraph
+    ```
+  </TabItem>
+  <TabItem value="macOSx86" label="macOS x86">
+    #### Latest Version
+    ```bash
+    curl -fsSL "https://github.com/neherlab/pangraph/releases/latest/download/pangraph-x86_64-apple-darwin" -o "pangraph" && chmod +x pangraph
+    ```
+    #### Specific Version
+    ```bash
+    curl -fsSL "https://github.com/neherlab/pangraph/releases/download/1.0.0/pangraph-x86_64-apple-darwin" -o "pangraph" && chmod +x pangraph
+    ```
+  </TabItem>
+  <TabItem value="macOSArm64" label="macOS ARM64">
+    #### Latest Version
+    ```bash
+    curl -fsSL "https://github.com/neherlab/pangraph/releases/latest/download/pangraph-aarch64-apple-darwin" -o "pangraph" && chmod +x pangraph
+    ```
+    #### Specific Version
+    ```bash
+    curl -fsSL "https://github.com/neherlab/pangraph/releases/download/1.0.0/pangraph-aarch64-apple-darwin" -o "pangraph" && chmod +x pangraph
+    ```
+  </TabItem>
+  <TabItem value="windowsX86" label="Windows x86">
+    #### Latest Version
+    ```bash
+    curl -fsSL "https://github.com/neherlab/pangraph/releases/latest/download/pangraph-x86_64-pc-windows-gnu.exe" -o "pangraph.exe" && chmod +x pangraph.exe
+    ```
+    #### Specific Version
+    ```bash
+    curl -fsSL "https://github.com/neherlab/pangraph/releases/download/1.0.0/pangraph-x86_64-pc-windows-gnu.exe" -o "pangraph.exe" && chmod +x pangraph.exe
+    ```
+  </TabItem>
+</Tabs>
+
+
+
+
+
+## optional dependencies - mmseqs2
+
+When building graphs, in addition to the native _minimap2_, Pangraph can use [_mmseqs2_](https://github.com/soedinglab/MMseqs2) as an alignment kernel.[^2] _mmseqs2_ is able to find homology between sequences with up to around 30% sequence divergence, at the cost of higher computational time.
 
 Use of this kernel requires installation of _mmseqs2_. This can be done for example using conda with:
 
@@ -38,4 +138,6 @@ conda install -c conda-forge -c bioconda mmseqs2
 
 Pangraph was tested with _mmseqs2_ version 17.b804f.
 
-:::
+:::
+
+[^1]: This kernel can be selected with the `-k mmseqs` option when running the [`pangraph build`](../reference.md#pangraph-build) command.
diff --git a/docs/docs/installation/with-docker.md b/docs/docs/installation/with-docker.md
@@ -8,7 +8,7 @@ Run Pangraph CLI inside a Docker container.
 
 :::info[Note]
 
-The following instructions assume you have [Docker](https://www.docker.com/) installed
+The following instructions assume you have [Docker](https://www.docker.com/) installed and is familiar with the basics. Explanation of Docker is out of scope of this documentation. Refer to [Docker documentation](https://docs.docker.com) if necessary.
 
 :::
 
@@ -21,14 +21,47 @@ docker pull neherlab/pangraph
 or pull a particular version
 
 ```shell
-docker pull neherlab/pangraph:1.0
+docker pull neherlab/pangraph:1
 ```
 
-Run pangraph commands described in [Usage](../reference.md) as follows:
+Run pangraph commands described in [CLI reference](../reference.md) or [Tutorials](/category/tutorial) as in following examples:
 
 ```shell
-docker run -it --rm neherlab/pangraph --help
-docker run -it --rm neherlab/pangraph build my.fasta
+docker run -it --rm neherlab/pangraph pangraph --help
+
+# Mount current directory to /data and run as current user
+docker run -it --rm --volume="$(pwd):/data" --user="$(id -u):$(id -g)" neherlab/pangraph pangraph build /data/input.fasta -o /data/pangraph.json
 ```
 
+:::info[Note]
+
+Don't forget to [add volumes](https://docs.docker.com/engine/storage/volumes/#syntax) to be able to access data on the host. You might also want to [run docker container as a non-root user](https://docs.docker.com/engine/containers/run/#user).
+
+:::
+
+
+## Extending the image
+
+You can base your own containers based on pangraph image and add your own software and functionality, for example:
+
+```dockerfile
+FROM neherlab/pangraph:1
+
+RUN sudo apt-get update && sudo apt-get install python3
 
+COPY my-script.py /usr/bin/my-script.py
+
+# ... remainder of your image
+
+```
+
+or you can add [standalone](standalone.md) pangraph binaries to any image:
+
+```dockerfile
+FROM my-org/my-image
+
+RUN curl -fsSL "https://github.com/neherlab/pangraph/releases/latest/download/pangraph-x86_64-unknown-linux-gnu" -o "/usr/bin/pangraph" && chmod +x /usr/bin/pangraph
+
+# ... remainder of your image
+
+```
diff --git a/docs/docusaurus.config.ts b/docs/docusaurus.config.ts
@@ -62,7 +62,7 @@ const config: Config = {
     prism: {
       theme: prismThemes.vsLight,
       darkTheme: prismThemes.vsDark,
-      additionalLanguages: ['bash', 'powershell'],
+      additionalLanguages: ['bash', 'powershell', 'docker'],
     },
   } satisfies Preset.ThemeConfig,
 

diff --git a/docs/package.json b/docs/package.json
@@ -22,7 +22,7 @@
     "@easyops-cn/docusaurus-search-local": "^0.48.5",
     "@mdx-js/react": "^3.0.0",
     "clsx": "^2.0.0",
-    "prism-react-renderer": "^2.3.0",
+    "prism-react-renderer": "^2.4.1",
     "react": "^18.0.0",
     "react-dom": "^18.0.0",
     "rehype-katex": "^7.0.1",