Skip to content

Storage connectors

Configure where Silex stores website data and assets.

Storage connectors are enabled and configured entirely through the environment variables below (STORAGE_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

Storage connectors handle the persistence layer: saving website HTML/CSS, assets, and metadata. Silex comes with one built-in option to store sites:

  • GitLab: store in GitLab repositories with OAuth authentication

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

Storage and publishing are configured separately. See Hosting connectors.

Prerequisites

Filesystem storage (development only)

The fs connector stores websites on the disk of the server, in SILEX_FS_ROOT, with no user accounts. 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 storage

Store websites in GitLab repositories with per-user authentication.

Prerequisites

  1. GitLab instance (gitlab.com or self-hosted)
  2. OAuth application registered in GitLab
  3. Environment variables set on your Silex server

OAuth app setup

On your GitLab instance:

  1. Go to Admin → Applications (or your profile → Settings → Applications)
  2. Click New application
  3. Fill in:
  4. Name: Silex
  5. Redirect URI: https://your-silex.com/api/connector/login/callback?type=storage&connectorId=gitlab
  6. Scopes: api, write_repository, read_user
  7. Copy the Application ID and Secret

Set environment variables

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

For self-hosted GitLab:

GITLAB_DOMAIN=https://gitlab.mycompany.com

Always include the scheme

GITLAB_DOMAIN must start with https://. Silex appends paths directly to this value (GITLAB_DOMAIN + /oauth/token), so a bare gitlab.com produces an invalid URL and authentication fails.

This works with any GitLab-compatible instance, not just gitlab.com: a self-hosted GitLab, Framagit, JiHuLab and others.

How it works

  • Each user connects with their GitLab account
  • Each website is a repository in their GitLab namespace
  • Website data: website.json in the repo
  • Website metadata: .website.json in the repo
  • Assets: assets/ directory
  • Users see only their own repositories

Repository structure:

my-silex-website/
├── website.json
├── .website.json
└── assets/
    ├── logo.png
    └── hero.jpg

Multiple GitLab instances

To support both gitlab.com and a self-hosted instance:

STORAGE_CONNECTORS=gitlab,gitlab2
GITLAB_CLIENT_ID=app-id-for-gitlab.com
GITLAB_CLIENT_SECRET=secret-for-gitlab.com
GITLAB_DOMAIN=https://gitlab.com
GITLAB2_CLIENT_ID=app-id-for-self-hosted
GITLAB2_CLIENT_SECRET=secret-for-self-hosted
GITLAB2_DOMAIN=https://gitlab.mycompany.com

Each entry in STORAGE_CONNECTORS gets its own button in the editor, labelled with GITLAB_DISPLAY_NAME / GITLAB2_DISPLAY_NAME.

Sites stored on FTP

Silex has no FTP storage connector anymore, so remove ftp from STORAGE_CONNECTORS when you upgrade. The sites stay on the FTP server, one folder per site. Users can download a site's folder and open it in Silex Desktop. See Move a site stored on FTP to Silex Desktop.

Troubleshooting

GitLab OAuth failing

Check that: - OAuth app is registered in GitLab - Redirect URI matches exactly: https://your-silex.com/api/connector/login/callback?type=storage&connectorId=gitlab - Credentials are correct: GITLAB_CLIENT_ID and GITLAB_CLIENT_SECRET - Domain is set: GITLAB_DOMAIN=https://gitlab.com

Test OAuth by visiting the login URL in a browser:

https://your-silex.com/api/connector/auth?type=storage&connectorId=gitlab

See also

Edit this page on GitLab