Skip to content

Hosting connectors

Configure where Silex publishes built websites.

Hosting connectors are enabled and configured entirely through the environment variables below (HOSTING_CONNECTORS, GITLAB_*) — that is the supported way on Docker and from-source. See Server configuration → Extending the server if the built-in connectors don't cover your need.

Overview

Hosting connectors handle publication: they receive the compiled HTML, CSS, and assets and deploy them to a live URL. Silex includes one built-in connector to host sites:

  • GitLab Pages: auto-publish to GitLab Pages via CI/CD

A filesystem connector (fs) also exists. It is for developing Silex only.

Unlike storage connectors, hosting is typically a one-way operation: Silex publishes to it but doesn't download from it.

Prerequisites

Filesystem hosting (development only)

The fs connector writes published files to SILEX_FS_HOSTING_ROOT. It is the default of a server started without configuration, and it is only there to debug Silex. Do not use it to host sites.

GitLab Pages hosting

Auto-publish to GitLab Pages via CI/CD.

Prerequisites

  1. GitLab repository in your storage connector
  2. CI/CD pipeline that runs build awesome and builds the site
  3. GitLab Pages enabled for your project

Setup

HOSTING_CONNECTORS=gitlab
GITLAB_CLIENT_ID=your-app-id
GITLAB_CLIENT_SECRET=your-app-secret
GITLAB_DOMAIN=https://gitlab.com

Same OAuth app as storage GitLab connector.

How it works

  1. User connects with GitLab (OAuth)
  2. Website is stored in a GitLab repository
  3. When user publishes, Silex:
  4. Commits the website source to the repo
  5. Triggers the CI/CD pipeline (.gitlab-ci.yml)
  6. Pipeline runs sh build.sh (the build awesome compilation, generated from build.json)
  7. Pipeline deploys the _site/ folder to GitLab Pages
  8. Site is live at https://username.gitlab.io/project-name

.gitlab-ci.yml

Silex generates the CI config at each publication; it only runs sh build.sh and should not be edited. To customize the build, edit build.json instead. See Customize the build.

Custom domain

In your GitLab project settings:

  1. Go to Deployments → Pages
  2. Click New domain
  3. Enter your domain (e.g., my-site.com)
  4. Follow DNS setup instructions

Publishing with FTP or as a zip

The Silex server has no FTP or download connector anymore, so remove ftp and download from HOSTING_CONNECTORS when you upgrade. The build runs on the forge: from there, build.json can upload the site to an FTP or SFTP server, and the forge keeps a zip of each build. See Publish to your own web host and Get your site as a zip file. Silex Desktop can also publish with FTP or SFTP.

Job management

Hosting connectors receive a jobManager to track publication progress:

interface JobManager {
  addJob(data: JobData): string
  setJobData(jobId: string, data: JobData): void
  getJobData(jobId: string): JobData | null
}

The connector updates job status as publication progresses. See server events for listening to publication lifecycle.

Troubleshooting

GitLab Pages not deployed

Check: - .gitlab-ci.yml exists in the repo - CI/CD is enabled in GitLab project settings - Pipeline succeeded (check Build → Pipelines) - Pages are enabled (Deployments → Pages)

See also

Edit this page on GitLab