impostor/infra.md

Server

graph TD
  Internet --> Nginx

  Nginx --> Traefik
  Traefik --> Gitea
  Gitea --> GiteaDB[(Gitea data / SQLite)]

  Traefik --> WoodpeckerServer
  WoodpeckerServer --> WoodpeckerDB[(Woodpecker data / SQLite)]
  WoodpeckerServer --> WoodpeckerAgent
  WoodpeckerAgent --> DockerSocket[(Docker)]

  Traefik --> WebApp
  WebApp --> MySQL[(MySQL)]
  WebApp --> Softwares[(Volume)]

  Droparea --> Softwares

  Nginx --> Discourse
  Discourse --> ForumDB[(Postgres)]
  Discourse --> Redis[(Redis)]

  Nginx --> Wiki
  Wiki --> WikiDB[(Postgres)]

TIC-80 Pipeline

This document describes the Woodpecker CI pipeline used to build, export, upload, and publish a TIC-80 game project.

---

Overview

The pipeline performs the following steps:

1. Build the TIC-80 project using a custom Docker image
2. Export the game to .tic and HTML formats
3. Upload artifacts to a remote server via SCP
4. Notify an update server to publish the new version

The pipeline is driven by environment variables so it can be reused across projects.

---

Global Environment

environment: &environment
  GAME_NAME: mranderson
  GAME_LANG: lua

• GAME_NAME: Project name (used for all outputs)
• GAME_LANG: Source language used by TIC-80 (Lua)

The anchor (&environment) allows reuse across steps.

---

Step 1: Build & Export

- name: build
  image: git.teletype.hu/internal/tic80pro:latest
  environment:
    <<: *environment
    XDG_RUNTIME_DIR: /tmp
  commands:
    - make build
    - make export

What it does:

• Uses a custom TIC-80 Pro Docker image hosted in Gitea
• Runs the Makefile build target to assemble source files
• Runs the export target to generate:
  • .tic cartridge
  • .html.zip web build

---

Step 2: Artifact Upload

- name: artifact
  image: alpine
  environment:
    <<: *environment
    DROPAREA_HOST: vps.teletype.hu
    DROPAREA_PORT: 2223
    DROPAREA_TARGET_PATH: /home/drop
    DROPAREA_USER: drop
    DROPAREA_SSH_PASSWORD:
      from_secret: droparea_ssh_password
  commands:
    - apk add --no-cache openssh-client sshpass
    - mkdir -p /root/.ssh
    - sshpass -p $DROPAREA_SSH_PASSWORD scp -o StrictHostKeyChecking=no -P $DROPAREA_PORT \
        $GAME_NAME.$GAME_LANG \
        $GAME_NAME.tic \
        $GAME_NAME.html.zip \
        $DROPAREA_USER@$DROPAREA_HOST:$DROPAREA_TARGET_PATH

What it does:

• Installs SCP tooling in a minimal Alpine container
• Uploads:
  • Source file
  • TIC-80 cartridge
  • HTML export ZIP
• Uses secrets for SSH authentication

---

Step 3: Update Notification

- name: update
  image: alpine
  environment:
    <<: *environment
    UPDATE_SERVER: https://games.vps.teletype.hu
    UPDATE_SECRET:
      from_secret: update_secret_key
  commands:
    - apk add --no-cache curl
    - curl "$UPDATE_SERVER/update?secret=$UPDATE_SECRET&name=$GAME_NAME&platform=tic80"

What it does:

• Sends an HTTP request to the update server
• Notifies that a new TIC-80 build is available
• Uses a secret key to authorize the update

---

Result

After a successful run:

• The game is built and exported
• Artifacts are uploaded to the server
• The public game index is updated automatically

This pipeline enables fully automated TIC-80 releases using open tools and infrastructure.

TIC-80 Makefile Project Builder

This Makefile provides a simple, reproducible workflow for building TIC-80 Lua projects from multiple source files. It is designed for small indie or experimental projects where the source code is split into logical parts and then merged into a single .lua cartridge.

---

Overview

The workflow is based on four core ideas:

• Source code is split into multiple Lua files inside an inc/ directory
• A project-specific .inc file defines the build order
• All source files are concatenated into one final .lua file
• TIC-80 is used in CLI mode to export runnable artifacts

This approach keeps the codebase modular while remaining compatible with TIC-80’s single-file cartridge model.

---

Project Structure

project-root/
├── inc/
│   ├── core.lua
│   ├── player.lua
│   └── world.lua
├── mranderson.inc
├── Makefile
└── README.md

• inc/ contains all Lua source fragments
• <project>.inc defines the order in which files are merged
• <project>.lua is generated automatically

---

The .inc File

The .inc file is a plain text file listing Lua source files in build order:

core.lua
player.lua
world.lua

The order matters. Files listed earlier are concatenated first and must define any globals used later.

---

Usage

Build (default)

make build

• Reads mranderson.inc
• Concatenates files from inc/
• Produces mranderson.lua

Export (TIC-80)

make export

• Loads the generated Lua file into TIC-80 (CLI mode)
• Saves a .tic cartridge
• Exports an HTML build

Export Assets

make export_assets

• Purpose: Extracts asset sections (PALETTE, TILES, SPRITES, MAP, SFX, MUSIC) from the compiled <project>.lua file.
• Mechanism: Uses sed to directly parse the generated <project>.lua and saves the extracted data into inc/meta/meta.assets.lua. This file can then be used to embed the asset data directly into other parts of the project or for version control of visual assets.

Import Assets

The import_assets target was considered during development but is currently not part of the build workflow. Asset handling for TIC-80 projects within this Makefile relies solely on direct extraction (export_assets) from the built Lua cartridge, rather than importing external asset definitions. This target may be implemented in the future if a need for pre-build asset injection arises.

Watch Mode

make watch

• Performs an initial build
• Watches the inc/ directory and .inc file
• Rebuilds automatically on any change

Requires fswatch to be installed.

---

Generated Artifacts

File	Description
<project>.lua	Merged Lua source (input for TIC-80)
<project>.tic	TIC-80 cartridge
<project>.html	Web export
<project>.html.zip	Packaged HTML build

---

Design Goals

• Keep TIC-80 projects modular
• Avoid manual copy-paste between files
• Enable fast iteration and experimentation
• Remain fully compatible with open-source tooling

This Makefile is intentionally minimal and transparent, favoring simplicity over abstraction.

---

Requirements

• make
• tic80 available in PATH
• fswatch (only for watch mode)

---

License

MIT License — free to use, modify, and redistribute.