-
Notifications
You must be signed in to change notification settings - Fork 0
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
link/redirect to content moved to try.perm.pub
- Loading branch information
Showing
6 changed files
with
44 additions
and
174 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,74 +1,4 @@ | ||
| # Containers | ||
|
|
||
| Running `basecast` inside an [OCI container](https://opencontainers.org/), | ||
| often known as a Docker container, avoids many typical installation problems. | ||
| Containers can be run using `podman` or `docker`, | ||
| with `podman` being the recommended option. | ||
| However, replacing `podman` with `docker` will _probably_ still work. | ||
| Podman is a superior drop-in replacement to the `docker` tool. | ||
|
|
||
| ### Step One | ||
|
|
||
| The first step is to install `podman` if it is not already installed. | ||
|
|
||
| [Get Started with Podman](https://podman.io/get-started){ .md-button .md-button--primary target='_blank' } | ||
|
|
||
| ### Step Two | ||
|
|
||
| Define a shell function named `basecast` to run the container image | ||
| [`docker.io/castedo/basecast`](https://hub.docker.com/r/castedo/basecast/tags). | ||
|
|
||
| In the bash shell, this is achieved with the following lines: | ||
|
|
||
| ```bash | ||
| basecast() { | ||
| podman run --rm -v=$PWD:/mnt -w=/mnt docker.io/castedo/basecast basecast "$@" | ||
| } | ||
| ``` | ||
|
|
||
| You can manually enter these lines at the bash command line or copy them into an | ||
| initialization file (e.g., `.bashrc`). | ||
|
|
||
| !!! warning | ||
|
|
||
| Basecast can ONLY access relative file paths below the current directory | ||
| when run inside a container via the above bash function. | ||
|
|
||
|
|
||
| ### Step Three | ||
|
|
||
| After defining the shell function mentioned above, you can test it by simply typing the shell command | ||
| as if `basecast` were installed locally: | ||
|
|
||
| ```bash | ||
| basecast | ||
| ``` | ||
|
|
||
| The first execution of this function will trigger a one-time download of the container image (almost 1GB!), | ||
| and then `basecast` will display the [command line](usage.md) help. | ||
|
|
||
| If you are running with SELinux, you may need to insert `--security-opt label=disable` | ||
| after `podman run`. | ||
|
|
||
| NOTE: Running this shell command will share the local current working directory with the | ||
| container. Therefore, only relative paths to files under the current working directory | ||
| will work. | ||
|
|
||
| ### Step Four (Optional) | ||
|
|
||
| When generating HTML previews of a baseprint, it can be convenient to run a local web | ||
| server that automatically refreshes the preview web page when it is regenerated. | ||
|
|
||
| The Basecast container image includes such a web server. | ||
| It can be used by setting up a second shell function similar to the `basecast` function in step two. | ||
|
|
||
| ```bash | ||
| live-basecast() { | ||
| podman run --rm -v=.:/mnt -w=/mnt -p=8080:8080 -it \ | ||
| docker.io/castedo/basecast bash -c "live-server site & basecast -o=site $*" | ||
| } | ||
| ``` | ||
|
|
||
| ### Done | ||
|
|
||
| [Learn how to use `basecast`](usage.md){ .md-button } | ||
| --- | ||
| template: redirect.html | ||
| location: "https://try.perm.pub/howto/basecast_container/" | ||
| --- |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,50 +1,4 @@ | ||
| # Package Install | ||
|
|
||
| Basecast is developed and tested to run locally on Linux, specifically Fedora. | ||
| For Mac and Windows you should [run `basecast` via containers](containers.md). | ||
| Installing `basecast` locally on distributions other than Fedora may require additional effort. | ||
| Looking at the [files used to create the Basecast container | ||
| images](https://gitlab.com/castedo/basecast/-/tree/main/oci_images) may be helpful. | ||
|
|
||
|
|
||
| ## Basic Installation | ||
|
|
||
| The following common tools must be installed: `git`, `pip` and `npm`. | ||
|
|
||
| [Installing pandoc](https://pandoc.org/installing.html#linux) is required, | ||
| with a minimum version of 3.1.6.2. | ||
|
|
||
| Basecast is a Python package and can be installed as a user-specific package using the following command: | ||
|
|
||
| ``` | ||
| python3 -m pip install --user basecast@git+https://gitlab.com/castedo/basecast.git | ||
| ``` | ||
|
|
||
| You also need to install the following NPM package: | ||
|
|
||
| ``` | ||
| npm install pandoc-katex-filter | ||
| ``` | ||
|
|
||
|
|
||
| ## PDF Support | ||
|
|
||
| The basic installation only provides HTML previews, | ||
| which give you an idea of how the generated PDF will appear. | ||
| To enable PDF support, you need to install two additional packages: | ||
|
|
||
| 1. [WeasyPrint Installation](https://doc.courtbouillon.org/weasyprint/stable/first_steps.html). | ||
| 2. The `pdf` extra from the `basecast` package: | ||
|
|
||
| ``` | ||
| python3 -m pip install --user basecast[pdf]@git+https://gitlab.com/castedo/basecast.git | ||
| ``` | ||
|
|
||
|
|
||
| ## System Installation | ||
|
|
||
| If you prefer system-wide installations instead of user-specific ones, make the following | ||
| replacements to the above instructions: | ||
|
|
||
| * Replace `python3 -m pip install --user ...` with `sudo python3 -m pip install ...`. | ||
| * Replace `npm install ...` with `sudo npm install -g pandoc-katex-filter ...`. | ||
| --- | ||
| template: redirect.html | ||
| location: "https://try.perm.pub/howto/install_basecast/" | ||
| --- |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,20 @@ | ||
| {% extends "main.html" %} | ||
|
|
||
| {% block extrahead %} | ||
| {{ super() -}} | ||
| <meta http-equiv="refresh" content="3; URL={{page.meta.location}}"> | ||
| {% endblock extrahead %} | ||
|
|
||
| {% block content %} | ||
| <center> | ||
| <p> | ||
| This page is now located at: | ||
| </p> | ||
|
|
||
| <a href="{{page.meta.location}}">{{page.meta.location}}</a> | ||
|
|
||
| <p> | ||
| You should be be automatically redirected in 3 seconds. | ||
| </p> | ||
| </center> | ||
| {% endblock content %} |