From 9fcaae9ede90b318c472eb3ec13897ce13d51c1e Mon Sep 17 00:00:00 2001 From: Sapphire Cat Date: Sun, 8 Oct 2023 14:31:40 -0400 Subject: [PATCH] Container build mode! Added the `doc` folder, because putting everything for two build systems in the README was cluttered. Moved `/build.sh` to `/build/compile.sh`. --- .dockerignore | 21 +++++++++++++++++++++ .gitignore | 1 + README.md | 32 +++++++++++++++++++------------- build/Containerfile | 9 +++++++++ build.sh => build/compile.sh | 7 ++++++- build/container.sh | 10 ++++++++++ doc/container.md | 28 ++++++++++++++++++++++++++++ doc/host-side.md | 36 ++++++++++++++++++++++++++++++++++++ 8 files changed, 130 insertions(+), 14 deletions(-) create mode 100644 .dockerignore create mode 100644 build/Containerfile rename build.sh => build/compile.sh (81%) create mode 100644 build/container.sh create mode 100644 doc/container.md create mode 100644 doc/host-side.md diff --git a/.dockerignore b/.dockerignore new file mode 100644 index 0000000..7c4536e --- /dev/null +++ b/.dockerignore @@ -0,0 +1,21 @@ +# auto generated or typically secret +**/dist +**/node_modules/ +**/vendor +.git +npm-debug.log +.coverage +.coverage.* +.env +.aws +build/.install + +# developer-facing +build/Dockerfile +*.md +.editorconfig +.git +.idea +.vscode +# if we get more swapfiles than this, we should probably fix vim first... +**/.*.sw[a-p] diff --git a/.gitignore b/.gitignore index 0db4cc4..66e3c36 100644 --- a/.gitignore +++ b/.gitignore @@ -3,3 +3,4 @@ /dist/ /node_modules/ +/build/.install diff --git a/README.md b/README.md index d3fc195..b0a6a38 100644 --- a/README.md +++ b/README.md @@ -11,26 +11,32 @@ Quarter-square triangle design assistant **[https://sapphirecat.github.io/quilt-draw/](https://sapphirecat.github.io/quilt-draw/)** +This is the *recommended* option for using Quilt Draw. + ## Development -Initial setup: +There are now two major options: + +- **[Host-side mode](doc/host-side.md)** using [Node](https://nodejs.dev/),\* + [Yarn](https://classic.yarnpkg.com/lang/en/),\* + a POSIX shell (Linux/Mac/BSD), and a static HTTP server +- **[Container mode](doc/container.md)** using [Podman](https://podman.io)\*, + [Docker](https://www.docker.com/)\*, or compatible -1. Clone the repo -2. `yarn install --frozen-lockfile` to download everything - (get [Yarn 1.x](https://classic.yarnpkg.com/) if you need it) -3. `./build.sh -d` to do an initial build of the project: - the `-d` for development mode +Host-side mode requires the development environment as a whole to be installed +on your computer, and is primarily focused on supporting Linux. +Container mode should work on any OS with Docker-compatible tools. -NOTE: When run without options, `./build.sh` will create a release/minified -version. +In addition, container mode **does not require** a separate HTTP server to view +the files in a Web browser, as the container provides this feature. -Ongoing development: +\* Links are provided for convenience, and DO NOT represent an endorsement +of the software or related web sites. -* `yarn run dev-server` -* Open [localhost:8080](http://localhost:8080/) in your browser +# Issue Tracker -This will only automatically pick up changes to `src/app.ts`. Other changes -need copied over manually. +Report problems or request features at +[GitHub Issues](https://github.com/sapphirecat/quilt-draw/issues/). # License diff --git a/build/Containerfile b/build/Containerfile new file mode 100644 index 0000000..cadd311 --- /dev/null +++ b/build/Containerfile @@ -0,0 +1,9 @@ +FROM docker.io/library/node:lts +RUN npm install --global http-server +ENV MODE=--dev +ENV PORT=9001 + +COPY . /app +RUN ["/bin/sh", "-c", "/app/build/compile.sh $MODE"] +EXPOSE ${PORT} +CMD ["/bin/sh", "-c", "cd /app/dist && http-server"] diff --git a/build.sh b/build/compile.sh similarity index 81% rename from build.sh rename to build/compile.sh index 43765e5..92ea0c8 100755 --- a/build.sh +++ b/build/compile.sh @@ -1,7 +1,7 @@ #!/bin/sh set -eu -cd "$(dirname "$0")" +cd "$(dirname "$0")/.." usage() { cat <&1)" ] ; then + yarn install --frozen-lockfile + touch build/.install +fi yarn run "${mode}" diff --git a/build/container.sh b/build/container.sh new file mode 100644 index 0000000..fbd443d --- /dev/null +++ b/build/container.sh @@ -0,0 +1,10 @@ +#!/bin/sh +set -eu + +cd "$(dirname "$0")/.." +cmd=podman +if ! command -v podman >/dev/null 2>&1 ; then + cmd=docker +fi + +exec "${cmd}" build -t quilt-draw:latest -f build/Containerfile . diff --git a/doc/container.md b/doc/container.md new file mode 100644 index 0000000..59fede6 --- /dev/null +++ b/doc/container.md @@ -0,0 +1,28 @@ +# Container mode, podman/Docker + +This documentation is part of the [Quilt Draw](../) project. + +Due to licensing concerns, these directions will feature the `podman` +command, but changing “podman” to “docker” is expected to be compatible +if the Docker engine is in use. + +## Manual (re)build + +1. Change to the repository directory +2. `podman build -t quilt-draw:latest -f build/Containerfile .` _or_ + on macOS/Linux, `./build/container.sh` + +This (always) builds **an image** tagged `quilt-draw:latest`. +It does not start a container; that is discussed below. + +## Running the container + +* `podman run -it -p 9001:9001 quilt-draw:latest` +* Navigate to [localhost:9001](http://localhost:9001/) + +The container always listens on port 9001. To use a different port, +for example 8080, change the left side of the port-binding value: + + podman run --rm -it -p 8080:9001 quilt-draw:latest + +Use Ctrl+C to stop the container. diff --git a/doc/host-side.md b/doc/host-side.md new file mode 100644 index 0000000..be59b38 --- /dev/null +++ b/doc/host-side.md @@ -0,0 +1,36 @@ +# Host-side mode, macOS/Linux + +This documentation is part of the [Quilt Draw](../) project. + +## Initial setup + +1. Get [Yarn 1.x](https://classic.yarnpkg.com/) if you need it; `npm i -g yarn` + +## Manual rebuild + +1. Change to the repository directory +2. `./build/compile.sh -d` to do an initial build of the project: + the `-d` is for development mode + +_NOTE:_ When run without options, `./build/compile.sh` will create a +release (aka minified) version. + +## Ongoing development option + +* `yarn run dev-server` +* Open [localhost:8080](http://localhost:8080/) in your browser + +This will only automatically pick up changes to `src/app.ts`. Other changes +need copied over (from `src` to `dist`) manually. + +## Serving the files + +Assuming you are still in the repository directory, +one of the following may work to serve the `dist` directory +at an address of [localhost:9001](http://localhost:9001/): + +* `python3 -m http.server -d dist 9001` +* `php -t dist -S localhost:9001` +* `ruby -run -e httpd dist -p 9001` + +(Why 9001? _[It’s over 9000!](https://en.wikipedia.org/wiki/It%27s_Over_9000!)_)