Feat: extend Docker Support

[almereyda]

These commits package Quartz as a container here at the GitHub container registry when a new tag is pushed:

• Package quartz

The CI workflow is prepared to also push to Docker Hub. There is also a workflow dispatch trigger to create manual builds. The configuration could be parametrised more in the future.

The Dockerfile has been minimally modified to conform to the OCI standard with regards to the entrypoint and its command, plus has been extended with the missing git dependency to be able to use the build command.

The documentation has been extended with some examples on how to use the image.

The documentation expects the image to be pushed to ghcr.io/jackyzha0/quartz.

[almereyda]

An exemplary pipeline run and artifact were generated into:

• Build and Push · allmende/quartz@c98c542
• Package quartz

[almereyda]

This image also supports running in GitLab CI to push into GitLab Pages:

image:
  name: ghcr.io/allmende/quartz:v4
  entrypoint: [""]

pages:
  rules:
    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH

  stage: deploy
  environment: live

  before_script:
    - cd /usr/src/app
    - mkdir -p public

  script:
    - cp $CI_PROJECT_DIR/quartz.*.ts .
    - npx quartz build -d $CI_PROJECT_DIR/content
    - mv public $CI_PROJECT_DIR

  artifacts:
    paths:
      - public

The minimal example for the file system layout of a content repository without including a whole fork of Quartz looks like this:

.
├── content
│   └── index.md
├── quartz.config.ts
└── quartz.layout.ts

[bachrc]

there seem to be some issues with the linting, you can see the action logs

[almereyda]

I've pushed a commit to fix the linter issues, which seem to be resolved.

While there is no definition of a content repository for quartz, we have updated our patterns.

.
├── .quartz
│   ├── quartz
│   │   └── components
│   │       ├── Backlinks.tsx
│   │       └── Footer.tsx
│   ├── quartz.config.ts
│   └── quartz.layout.ts
├── content
│   └── index.md
└── .gitlab-ci.yml

The CI needs to be adapted as well:

image:
  name: ghcr.io/allmende/quartz:v4
  entrypoint: [""]

pages:
  rules:
    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH

  stage: deploy
  environment: live

  before_script:
    - cd /usr/src/app
    - mkdir -p public

  script:
    - cp -R $CI_PROJECT_DIR/.quartz/* .
    - npx quartz build -d $CI_PROJECT_DIR/content
    - mv public $CI_PROJECT_DIR

  artifacts:
    paths:
      - public

By using the dot pattern for the Quartz configuration, we can cleanly separate the concerns of content and configuration and can still apply a custom overlay, e.g. here also for certain components.

[jackyzha0]

can you illustrate the working directory structure here?

[almereyda]

Good suggestion.

My exemplary way to use this container has also changed a bit, as illustrated in my previous comment. I will update the file.

[almereyda]

I have now added 3b58b2f to address your comment.

From your perspective, does the explanation still lack suitable examples to work with this image?

[aarnphm]

we can possibly build for multiple platform here, since quartz has been battle tested on Linux and Darwin.

[almereyda]

Thanks from looking into this. Should be a trivial change to add more targets here.

Which do you have in mind? linux/arm64 is the only other notable one I could think of for containers.

How would one build a container for Darwin?

[aarnphm]

linux/arm64, darwin/arm64, maybe even most of the node covered architecture.

[aarnphm]

we should use mount cache here. see https://docs.docker.com/build/guide/mounts/

[almereyda]

Let me investigate and add a patch based on what I can come up with.

[aarnphm]

hi there, since #1192 we have something similar to what you propose here?

can you maybe update this PR to include docs update as well as Dockerfile improvement instead?

One thing is that with the main quartz container users can do something like this

docker run --rm --platform linux/amd64 -p 8080:8080 \
	-v /path/to/vault:/usr/src/app/content ghcr.io/jackyzha0/quartz:latest

[almereyda]

I hadn't seen #1192, thanks for the update. Will need to look into it.