Publishing from Silex Desktop

Silex Desktop is alpha software

Publishing to a git forge is new. If something here does not match what you see, say so on the forum or in an issue on the Silex repository.

Silex Desktop publishes your website by sending it to a git forge. Your site lives in a repository you own, the forge builds it, and the forge serves it. There is no Silex server in the middle.

Three forges are supported: GitLab, Forgejo (which is what Codeberg runs) and SourceHut.

What you need first

Silex reads what your forge knows through the command line of that forge: glab for GitLab, tea for Forgejo and Codeberg, hut for SourceHut. Install the one your forge uses and sign in with it. Silex looks for these programs once, the first time it runs, so install it before you open Silex Desktop for the first time. Without it, Silex says it does not know how to publish this website.

Silex sends your website with the git of your computer. It never asks you for a password or a passphrase, so git has to be able to push on its own: an SSH key the forge knows, or a credential helper that holds your token.

The repository on the forge has to be empty. GitLab ticks Initialize repository with a README when you create one, and a repository that already has a commit has a history your website shares nothing with. The push is refused, and Silex has no way out of that.

Before your first publication on Codeberg

Codeberg turns Actions off on every new repository. Nothing builds your site until you turn them on, whether the repository is public or private.

Open your repository on Codeberg, go to Settings, then the Units tab, and tick Actions. Publish again after that.

Codeberg also serves pages only from public repositories. A private repository can build your site, but nobody will be able to see it, not even you.

Silex tells you when a build never started and links you to the page where Actions are turned on. You do not have to remember this, but knowing it saves you a wait.

What Silex puts in your repository

When you publish, Silex writes five things next to your pages, then commits and pushes them:

File	Who owns it
public/	Silex. Your published pages, styles and images.
build.json	You. Created once with a default, never rewritten.
build.sh	Silex. Rebuilt from build.json at every publication.
.gitignore	You. Silex adds _site/ to it once and leaves the rest alone.
The pipeline file of your forge	Silex, until you say otherwise — see below.

The pipeline file is .gitlab-ci.yml on GitLab, .forgejo/workflows/pages.yml on Forgejo, and .build.yml on SourceHut. _site/ is where build.sh writes the built site, which is why it is ignored: it is made again at every build.

Taking over the pipeline file

Every pipeline file Silex writes starts with this line:

# silexOverwrite: true

That line means Silex owns this file and will rewrite it at every publication. Delete the line and the file is yours — Silex will never touch it again.

Do that when you want to change something Silex does not offer as a setting:

• how long the build is allowed to take (see below),
• how often it runs, for a site that reads a data source,
• extra steps of your own.

You can undo it: put the line back and Silex takes the file over again at the next publication.

Changing the size of the build machine

Codeberg lends its build machines for free and asks that each job takes the size it needs, no more. Silex asks for the smallest one, codeberg-tiny, and writes it in the workflow:

jobs:
  pages:
    runs-on: codeberg-tiny
    timeout-minutes: 2

The name of the machine is a field of the publication window, Build machine name. Change it there to ask for a bigger machine, or to name the machines of a Forgejo that is not Codeberg. A name no machine on that server answers to means nothing ever builds your website, and Silex tells you so after a minute of waiting.

Label	CPU	Memory	Time allowed
codeberg-tiny	1	2 GB	2 min
codeberg-small	2	4 GB	5 min
codeberg-medium	4	8 GB	10 min

The memory figure includes what your build writes to disk, plus 2 GB of temporary space.

The time limit is not a field: Silex always writes timeout-minutes: 2, which is what codeberg-tiny is lent for. To give a bigger machine the time it comes with, remove the silexOverwrite line and raise timeout-minutes yourself.

Publishing again without opening Silex

Useful when your site reads a CMS or a data source: the content changed, the site did not, and you want a fresh build without opening Silex at all.

GitLab

On a schedule — the simplest for a site fed by data. Build → Pipeline schedules → New schedule, pick how often, target branch main. Your site rebuilds on its own.

From your CMS, with a trigger token. Create one in Settings → CI/CD → Pipeline trigger tokens, then call it from wherever your content lives:

curl --request POST \
  --form token=<your trigger token> \
  --form ref=main \
  "https://gitlab.com/api/v4/projects/<project id>/trigger/pipeline"

With a personal access token, if you already have one:

curl --request POST \
  --header "PRIVATE-TOKEN: <your token>" \
  "https://gitlab.com/api/v4/projects/<project id>/pipeline?ref=main"

The project id is on your project's home page, under its name.

By hand — Build → Pipelines → Run pipeline.

Forgejo and Codeberg

By hand — the Actions tab of your repository, pick the pages workflow, Run workflow.

From your CMS, with a token from Settings → Applications:

curl --request POST \
  --header "Authorization: token <your token>" \
  --header "Content-Type: application/json" \
  --data '{"ref":"main"}' \
  "https://codeberg.org/api/v1/repos/<owner>/<repo>/actions/workflows/pages.yml/dispatches"

On a schedule — Silex does not set one up, because it would rebuild your site whether or not anything changed. To add one, take the workflow file over (remove the silexOverwrite line) and add a schedule: next to workflow_dispatch::

on:
  push:
    tags:
      - '_silex_*'
  workflow_dispatch:
  schedule:
    - cron: '0 4 * * *'

SourceHut

The build manifest names where to clone from, so it can be sent on its own:

hut builds submit .build.yml

Where your site ends up

When the build finishes, Silex says your website is live and offers two buttons, View your website and Address and domain. What Silex knows of that address depends on the forge.

Codeberg and Forgejo. The publication window asks three things before sending: the domain that serves your pages, codeberg.page on Codeberg; the name of the build machine, codeberg-tiny on Codeberg; and a domain of your own, which stays empty unless you have one. Silex works out the address from the pages domain, your account name and the name of the repository, so it knows it from the first publication. A repository named pages is served at the root of your subdomain, any other one under a path named after it.

SourceHut. The publication window asks for the address pages.sr.ht serves your website at. The field is empty, because a wrong guess would publish over another website of yours. Leave it empty and the build still publishes to <your account>.srht.site, but Silex says it does not know the address.

GitLab. There is no field. Silex asks GitLab for the address before it sends your website, and GitLab has none until a build has finished. So the first publication ends on "Your website is built" and Silex saying it does not know the address. Publish a second time and the address is there. GitLab also keeps Pages to the members of the repository until you say otherwise, and Silex tells you when that is the case.

What you answer in the publication window is kept with your website and offered again the next time.

Address and domain opens a different page on each forge: the Pages settings of your project on GitLab, the settings where Actions are turned on for Codeberg and Forgejo, and pages.sr.ht on SourceHut. Pointing a domain of your own at your website is done on the forge, not in Silex. On Codeberg it goes in a .domains file in your repository.

When publishing fails

The repository has changes Silex does not have. Someone pushed from another machine. Silex merges nothing during a publication: it stops and tells you to open the website again from the list of websites. Opening it takes in what can be taken in, and you publish again. Changes that contradict yours are left to you and to the git client you already have.

Silex cannot reach the forge. You will see what git said. Silex never asks for a password or a passphrase, so the usual cause is that git cannot sign in on its own: an SSH key that the forge does not know, or a token that expired.

Codeberg did not build anything. Actions are turned off on the repository. See the top of this page.

Nothing seems to happen after a publication. Only a tag named _silex_… starts a build. If you tag your repository for your own reasons, that does not publish your site — which is on purpose.