paulononato/backstage
1
0
Fork 0
Code Issues Pull Requests Actions 23 Packages Projects Releases Wiki Activity

docs: update instructions for Techdocs setup with Docker

Browse Source 
Signed-off-by: Lari Mahlio <lari.mahlio@gmail.com>
This commit is contained in:
Lari Mahlio
2023-09-21 15:36:12 +03:00
parent 6c686fd98e
commit 89d5d32d4c
2 changed files with 26 additions and 4 deletions
Download Patch File Download Diff File Expand all files Collapse all files
.github/vale/Vocab/Backstage/accept.txt
+2
View File
@@ -268,12 +268,14 @@ parseable
Patrik
pattison
Peloton
PEP
performant
Performant
periskop
Periskop
permissioned
permissioning
pipx
plantuml
Platformize
Podman
docs/features/techdocs/getting-started.md
+24 -4
View File
@@ -263,22 +263,42 @@ Setting `generator.runIn` to `local` means you will have to make sure your
environment is compatible with techdocs.
You will have to install the `mkdocs` and `mkdocs-techdocs-core` package from
pip, as well as `graphviz` and `plantuml` from your OS package manager (e.g.
pip, optionally also `graphviz` and `plantuml` from your OS package manager (e.g.
apt).
You can do so by including the following lines right above `USER node` of your
`Dockerfile`:
```Dockerfile
RUN apt-get update && apt-get install -y python3 python3-pip
RUN pip3 install mkdocs-techdocs-core==1.1.7
RUN apt-get update && apt-get install -y python3 python3-pip python3-venv
ENV VIRTUAL_ENV=/opt/venv
RUN python3 -m venv $VIRTUAL_ENV
ENV PATH="$VIRTUAL_ENV/bin:$PATH"
RUN pip3 install mkdocs-techdocs-core
```
Please be aware that the version requirement could change, you need to check our
[`Dockerfile`](https://github.com/backstage/techdocs-container/blob/main/Dockerfile)
and make sure to match with it.
Note: We recommend Python version 3.7 or higher.
On a Debian-based Docker container, Python packages must be either installed using
the OS package manager or within a virtual environment (see the
[related PEP](https://peps.python.org/pep-0668/)). Alternative is to use e.g.
[pipx](https://pypa.github.io/pipx/) for installing Python packages in an isolated
environment.
The above Dockerfile snippet installs the latest `mkdocs-techdoc-core` package.
Version numbers can be found in the corresponding
[changelog](https://github.com/backstage/mkdocs-techdocs-core#changelog). In
case you want to pin the version, use the example below:
```Dockerfile
RUN pip3 install mkdocs-techdocs-core==1.2.3
```
Note: We recommend Python version 3.11 or higher.
> Caveat: Please install the `mkdocs-techdocs-core` package after all other
> Python packages. The order is important to make sure we get correct version of