Hosting connectors

Configure where Silex publishes built websites.

Overview

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

• Filesystem — Write to local disk (for static file serving)
• Download — Generate a ZIP file for manual deployment
• GitLab Pages — Auto-publish to GitLab Pages via CI/CD
• FTP — Upload directly to an FTP server

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

Prerequisites

• Understanding of server configuration
• Understanding of storage connectors
• For GitLab Pages: a GitLab account with CI/CD enabled

HostingConnector interface

All hosting connectors implement this interface:

export interface HostingConnector extends Connector {
  publish(
    session,
    websiteId,
    files,
    jobManager
  ): Promise<JobData>

  getUrl(session, websiteId): Promise<string>

  // Plus standard auth methods (isLoggedIn, setToken, etc.)
}

Filesystem hosting

Write published sites to a local directory for web server integration.

Setup

HOSTING_CONNECTORS=fs
SILEX_FS_HOSTING_ROOT=./silex/hosting

Or in Docker:

environment:
  HOSTING_CONNECTORS: fs
  SILEX_FS_HOSTING_ROOT: /silex/hosting
volumes:
  - ./silex-hosting:/silex/hosting

How it works

When a user publishes:

1. Silex compiles the website (build awesome (powered by Eleventy))
2. Files are written to {SILEX_FS_HOSTING_ROOT}/{websiteId}/
3. A web server (Nginx, Apache) can serve this directory publicly

Directory structure:

silex/hosting/
├── my-site-1/
│   ├── index.html
│   ├── about.html
│   ├── css/
│   │   └── style.css
│   └── assets/
│       ├── logo.png
│       └── hero.jpg
├── my-site-2/
│   ├── index.html
│   └── ...

Serving published sites

With Nginx

Create a server block in /etc/nginx/sites-available/silex-sites:

server {
  listen 80;
  server_name *.example.com;

  # Route each subdomain to a published site directory
  set $site_name $host;
  set $site_name ${}; # Extract subdomain

  root /silex/hosting;
  try_files /$site_name$uri /$site_name/index.html =404;
}

Or manually add domains:

server {
  listen 80;
  server_name my-site-1.example.com;
  root /silex/hosting/my-site-1;
  try_files $uri $uri/ /index.html =404;
}

server {
  listen 80;
  server_name my-site-2.example.com;
  root /silex/hosting/my-site-2;
  try_files $uri $uri/ /index.html =404;
}

Reload Nginx:

sudo systemctl reload nginx

With Apache

Create a virtual host file:

<VirtualHost *:80>
  ServerName my-site.example.com
  DocumentRoot /silex/hosting/my-site

  <Directory /silex/hosting/my-site>
    Options Indexes FollowSymLinks
    AllowOverride All
    Require all granted
    RewriteEngine On
    RewriteBase /
    RewriteRule ^index\.html$ - [L]
    RewriteCond %{REQUEST_FILENAME} !-f
    RewriteCond %{REQUEST_FILENAME} !-d
    RewriteRule . /index.html [L]
  </Directory>
</VirtualHost>

Enable the site:

sudo a2ensite my-site.example.com
sudo systemctl reload apache2

Configuration in code

const FsHosting = require('@silexlabs/silex/dist/server/connectors/FsHosting').FsHosting

module.exports = async function (config) {
  config.setHostingConnectors([
    new FsHosting(config, {
      path: process.env.SILEX_FS_HOSTING_ROOT || './silex/hosting',
    }),
  ])
}

Download connector

Generate a ZIP file for users to download and deploy manually.

Setup

HOSTING_CONNECTORS=download

How it works

When a user publishes:

1. Silex compiles the website (build awesome)
2. Files are zipped
3. A download link is provided in the UI
4. User downloads and extracts to their hosting

No special configuration needed. The download connector is built-in.

Use cases

• Deploy to Netlify, Vercel, or other static hosts
• Deploy to traditional hosting with FTP/SFTP
• Local development and testing

See Deploying to other hosting platforms for manual deployment instructions.

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=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 npm run build (build awesome compilation)
7. Pipeline deploys to GitLab Pages
8. Site is live at https://username.gitlab.io/project-name

.gitlab-ci.yml

Silex provides a default CI/CD config. You can customize it. See GitLab CI/CD customization.

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

Configuration in code

const GitlabHostingConnector = require('@silexlabs/silex-plugins').GitlabHostingConnector

module.exports = async function (config) {
  config.addHostingConnector(
    new GitlabHostingConnector(config, {
      clientId: process.env.GITLAB_CLIENT_ID,
      clientSecret: process.env.GITLAB_CLIENT_SECRET,
      domain: process.env.GITLAB_DOMAIN || 'gitlab.com',
    })
  )
}

FTP hosting

Upload directly to an FTP server.

Prerequisites

• FTP server with credentials and disk space

Setup

HOSTING_CONNECTORS=ftp
FTP_HOSTING_PATH=/public_html

Or in Docker:

environment:
  HOSTING_CONNECTORS: ftp
  FTP_HOSTING_PATH: /public_html

How it works

1. User connects with FTP credentials (host, port, username, password)
2. When user publishes:
3. Silex compiles the website (build awesome)
4. Files are uploaded via FTP to {FTP_HOSTING_PATH}/{websiteId}/
5. Site is immediately live (if web server is configured)

Typical FTP setup

public_html/
├── my-site-1/
│   ├── index.html
│   ├── css/style.css
│   └── assets/
├── my-site-2/
│   ├── index.html
│   └── ...

With DNS pointing my-site-1.com to your FTP server, the site is live at my-site-1.com/my-site-1/.

Configuration in code

const FtpConnector = require('@silexlabs/silex-plugins').FtpConnector
const { ConnectorType } = require('@silexlabs/silex/dist/server/types')

module.exports = async function (config) {
  config.addHostingConnector(
    new FtpConnector(config, {
      type: ConnectorType.HOSTING,
      path: process.env.FTP_HOSTING_PATH || '/public_html',
    })
  )
}

Comparison table

Feature	Filesystem	Download	GitLab Pages	FTP
Setup	Simple	Built-in	Medium (OAuth)	Simple
Automation	Manual	Manual	Automatic (CI/CD)	Automatic
Cost	Your server	Free	Free	Your FTP
Custom domain	Manual DNS	Manual	GitLab UI	Manual DNS
Scaling	Single server	File download	GitLab infra	Your server
Best for	Self-hosted	Testing	Teams + GitHub	Traditional hosting

Combining storage and hosting

Mix and match connectors for flexibility:

STORAGE_CONNECTORS=fs,gitlab
HOSTING_CONNECTORS=fs,download,gitlab,ftp

Users can store on GitLab and publish to FTP, or store locally and download as ZIP.

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 CI/CD → Pipelines) - Pages are enabled (Deployments → Pages)

FTP upload failing

Verify: - FTP server is reachable: telnet ftp.example.com 21 - Credentials are correct - Disk space available on FTP server - Path exists: cd /public_html in FTP client

Filesystem hosting not accessible

If sites are written but not visible:

1. Check permissions: ls -la ./silex/hosting/
2. Verify web server is running and configured to serve the directory
3. Check web server logs for errors

See also

• Storage connector setup
• Server configuration
• GitLab CI/CD customization — GitLab CI customization
• Deploying to other hosting platforms — Deploying to other platforms