💾 Archived View for d.moonfire.us › blog › 2018 › 08 › 24 › mfgames-writing-docker-and-ci captured on 2024-07-09 at 01:51:35. Gemini links have been rewritten to link to archived content

-=-=-=-=-=-=-

Working with MfGames Writing, CI, and Docker

Up a Level

One of the main points of having MfGames Writing[1] is to automate the publication process.

1: /tags/mfgames-writing/

Series

I appear to be writing a short series of post about the tools I use for publication and writing.

Semantic Versions and Releases[2]: Why semantic versioning helps with the writing process.

2: /blog/2018/08/13/publishing-processes/

Evolution of MfGames Writing[3]: A brief history and reasoning behind the tools.

3: /blog/2018/08/21/mfgames-writing-reasons/

First Steps Using MfGames Writing[4]: Starting a new project with MfGames Writing.

4: /blog/2018/08/22/mfgames-writing-init/

Adding Content to MfGames Writing[5]: Adding front and back matter to novels.

5: /blog/2018/08/23/mfgames-writing-content/

Working with MfGames Writing, CI, and Docker: Adding automatic building with commits.
Additional Formats for MfGames Writing[6]: How to create PDF, MOBI, DOCX, and HTML versions.

6: /blog/2018/08/25/mfgames-writing-formats/

Theming for MfGames Writing[7]: A light introduction on how to customize the output.

7: /blog/2018/08/26/mfgames-writing-themes/

Integrating Semantic Versioning into MfGames Writing[8]: Tying semantic releases into the process.

8: /blog/2018/08/27/mfgames-writing-releases/

Adding Scripts

We've installed the commands in a previous step, but hooking them up in the `package.json` makes life a lot easier.

{
  "name": "test-project",
  "private": true,
  "version": "0.0.0"
  "scripts": {
    "build:epub": "mfgames-writing-format build epub",
    "build:pdf": "mfgames-writing-format build pdf",
    "build:html": "mfgames-writing-format build html",
    "build:docx": "sed 's@@@g' < $npm_package_name-$npm_package_version.html | pandoc -f html -t docx -o $npm_package_name-$npm_package_version.docx",
    "build:mobi": "kindlegen $npm_package_name-$npm_package_version.epub",
    "build": "npm run build:epub && npm run build:mobi && npm run build:pdf && npm run build:html && npm run build:docx"
  }
}

Basically this sets up my basic suite of scripts that let me generate everything or one specific file.

$ npm run build:epub
$ npm run build

You can see we use a couple other programs like `pandoc` to make DOCX files from HTML or MOBI files using the EPUB file and `kindlegen`.

I use `$npm_package_name` to pull in the package name (as I said, I use them for consistency) which lets me produce files with a consistent pattern including the version number.

The other formats (HTML, PDF, etc) will be talked about in tomorrow's post[9].

9: /blog/2018/08/25/mfgames-writing-formats/

CI Configuration

I use GitLab[10] as my primary development platform. I like the company, the fact they open-source much of their code, and their features. Most important is that they provide private repos, which means I can have one repo for every novel I work on.

10: https://gitlab.com/

GitLab has a continual integration (CI) service which will automatically run whenever I push up code. This is controlled by the `.gitlab-ci.yml` file.

# This Docker image contains all the libraries and tools to generate files.
image: dmoonfire/mfgames-writing-js:1.1.1

stages:
    - publish

publish:
    stage: publish
    tags:
        - docker

    # Generate the various publication files.
    script:
        - npm ci
        - npm run build

    # Keeping artifacts means we can download them after the fact.
    artifacts:
        expire_in: 1 week
        paths:
            - "*.pdf"
            - "*.epub"
            - "*.mobi"
            - "*.docx"
            - "*.html"

If CI is turned on in GitLab and this file is present, then it will automatically run the commands in the `script` section. It then takes the resulting PDF, EPUB, MOBI, DOCX, and HTML files and zips them up to be found on the website. Basically this runs the same command that you can run manually which makes it easier to test.

Docker

In the `.gitlab-ci.yml` file, you may notice we use a Docker image `dmoonfire/mfgames-writing-js:1.1.1`. This is up on DockerHub[11] and includes the various programs and utilities needed to generate the files. Some of the formats, in specific WeasyPrint[12], have specific installations and I found that having a Docker image makes life a lot easier.

11: https://hub.docker.com/r/dmoonfire/mfgames-writing-js/

12: https://weasyprint.org/

The image contains: