Connecteurs de stockage

Configurez l'emplacement de stockage des données et ressources des sites web dans Silex.

Aperçu

Les connecteurs de stockage gèrent la couche de persistance : sauvegarde du HTML/CSS des sites web, des ressources et des métadonnées. Silex propose trois options intégrées :

• Système de fichiers (par défaut) — Stockage sur disque, adapté aux instances auto-hébergées
• GitLab — Stockage dans des dépôts GitLab avec authentification OAuth
• FTP — Stockage sur des serveurs FTP distants

Les connecteurs sont interchangeables : vous pouvez en utiliser un pour le stockage et un autre pour la publication. Un utilisateur pourrait stocker ses sites web sur GitLab mais publier sur un serveur FTP.

Prérequis

• Compréhension de la configuration serveur
• Pour GitLab : une instance GitLab et des identifiants d'application OAuth
• Pour FTP : un serveur FTP et des identifiants

Interface StorageConnector

Tous les connecteurs de stockage implémentent cette interface :

export interface StorageConnector extends Connector {
  // CRUD on websites
  listWebsites(session): Promise<WebsiteMeta[]>
  readWebsite(session, websiteId): Promise<WebsiteData | Readable>
  createWebsite(session, data): Promise<WebsiteId>
  updateWebsite(session, websiteId, data): Promise<void>
  deleteWebsite(session, websiteId): Promise<void>
  duplicateWebsite(session, websiteId): Promise<void>

  // CRUD on assets
  writeAssets(session, websiteId, files, status?): Promise<string[] | void>
  readAsset(session, websiteId, fileName): Promise<ConnectorFileContent>
  deleteAssets(session, websiteId, fileNames): Promise<void>

  // Metadata
  getWebsiteMeta(session, websiteId): Promise<WebsiteMeta>
  setWebsiteMeta(session, websiteId, data): Promise<void>

  // Auth
  isLoggedIn(session): Promise<boolean>
  setToken(session, token): Promise<void>
  logout(session): Promise<void>
  getUser(session): Promise<ConnectorUser | null>
  getOAuthUrl(session): Promise<string | null>
  getLoginForm(session, redirectTo): Promise<string | null>
  getSettingsForm(session, redirectTo): Promise<string | null>
  getOptions(formData): ConnectorOptions
}

Stockage par système de fichiers (par défaut)

Stockez les sites web dans des répertoires sur votre serveur.

Installation

Activez via les variables d'environnement :

STORAGE_CONNECTORS=fs
SILEX_FS_ROOT=./silex/storage

Ou dans Docker :

environment:
  STORAGE_CONNECTORS: fs
  SILEX_FS_ROOT: /silex/storage
volumes:
  - ./silex-storage:/silex/storage

Fonctionnement

• Chaque site web est un répertoire dans {SILEX_FS_ROOT}/{websiteId}/
• Données du site web : {websiteId}/website.json
• Métadonnées du site web : {websiteId}/.website.json
• Ressources : {websiteId}/assets/

Structure des répertoires :

silex/storage/
├── my-site-1/
│   ├── website.json
│   ├── .website.json
│   └── assets/
│       ├── logo.png
│       └── hero.jpg
├── my-site-2/
│   ├── website.json
│   ├── .website.json
│   └── assets/

Authentification

Le stockage par système de fichiers ne nécessite pas d'authentification. Tous les utilisateurs sur le serveur ont accès à tous les sites web (pas d'isolation multi-utilisateurs).

Pour les configurations multi-utilisateurs, utilisez le stockage GitLab.

Configuration en code

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

module.exports = async function (config) {
  config.setStorageConnectors([
    new FsStorage(config, {
      path: process.env.SILEX_FS_ROOT || './silex/storage',
    }),
  ])
}

Stockage GitLab

Stockez les sites web dans des dépôts GitLab avec authentification par utilisateur.

Prérequis

1. Instance GitLab (gitlab.com ou auto-hébergée)
2. Application OAuth enregistrée dans GitLab
3. Variables d'environnement définies sur votre serveur Silex

Configuration de l'application OAuth

Sur votre instance GitLab :

1. Allez dans Admin → Applications (ou votre profil → Settings → Applications)
2. Cliquez sur New application
3. Remplissez :
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. Copiez l'Application ID et le Secret

Définir les variables d'environnement

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

Pour un GitLab auto-hébergé :

GITLAB_DOMAIN=gitlab.mycompany.com

Fonctionnement

• Chaque utilisateur se connecte avec son compte GitLab
• Chaque site web est un dépôt dans l'espace de noms GitLab de l'utilisateur
• Données du site web : website.json dans le dépôt
• Métadonnées du site web : .website.json dans le dépôt
• Ressources : répertoire assets/
• Les utilisateurs ne voient que leurs propres dépôts

Structure du dépôt :

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

Configuration en code

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

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

Instances GitLab multiples

Pour prendre en charge à la fois gitlab.com et une instance auto-hébergée :

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

L'exemple de configuration de silex-platform montre comment procéder :

class GitlabConnector1 extends GitlabConnector {
  displayName = 'GitLab.com'
}

class GitlabConnector2 extends GitlabConnector {
  connectorId = 'gitlab2'
  displayName = 'Company GitLab'
}

config.addStorageConnector(new GitlabConnector1(config, {...}))
config.addStorageConnector(new GitlabConnector2(config, {...}))

Stockage FTP

Stockez les sites web sur un serveur FTP.

Prérequis

• Serveur FTP avec identifiants
• Connaissances de base en FTP

Installation

STORAGE_CONNECTORS=ftp
FTP_STORAGE_PATH=/public_html

Ou dans Docker :

environment:
  STORAGE_CONNECTORS: ftp
  FTP_STORAGE_PATH: /public_html

Fonctionnement

• Chaque site web est un répertoire dans {FTP_STORAGE_PATH}/{websiteId}/
• Les utilisateurs saisissent leurs identifiants FTP (hôte, port, nom d'utilisateur, mot de passe) dans l'interface
• Les sessions sont stockées par utilisateur (identifiants mis en cache dans la session du navigateur)
• Les fichiers sont envoyés via SFTP ou FTP traditionnel

Structure des répertoires sur le FTP :

public_html/
├── my-site-1/
│   ├── website.json
│   ├── .website.json
│   └── assets/
├── my-site-2/
│   ├── website.json
│   ├── .website.json
│   └── assets/

Configuration en code

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

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

Tableau comparatif

Fonctionnalité	Système de fichiers	GitLab	FTP
Complexité d'installation	Simple	Moyenne (OAuth)	Simple
Multi-utilisateurs	Pas d'isolation	Complète (OAuth par utilisateur)	Par session
Coût	Gratuit	Gratuit (ou auto-hébergé)	Votre serveur FTP
Sécurité	Disque local uniquement	OAuth + permissions des dépôts	Identifiants FTP en session
Mise à l'échelle	Serveur unique	Serveurs multiples (dépôts)	Serveur distant
Idéal pour	Développement, utilisateur unique	Équipes, utilisateurs multiples	Hébergement traditionnel

Combiner stockage et hébergement

Vous pouvez combiner les connecteurs : stocker sur GitLab mais publier en FTP :

STORAGE_CONNECTORS=gitlab
HOSTING_CONNECTORS=ftp

Les utilisateurs stockent leurs sites web sur GitLab et publient sur leur hébergement FTP.

Dépannage

L'OAuth GitLab échoue

Vérifiez que : - L'application OAuth est enregistrée dans GitLab - L'URI de redirection correspond exactement : https://your-silex.com/api/connector/login/callback?type=storage&connectorId=gitlab - Les identifiants sont corrects : GITLAB_CLIENT_ID et GITLAB_CLIENT_SECRET - Le domaine est défini : GITLAB_DOMAIN=gitlab.com

Testez l'OAuth en visitant l'URL de connexion dans un navigateur :

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

La connexion FTP échoue

Vérifiez que le serveur FTP fonctionne :

telnet ftp-server.com 21

Vérifiez les identifiants et le chemin :

ftp ftp-server.com
# Enter username and password
cd /public_html

Permissions du stockage par système de fichiers

Assurez-vous que le processus Silex peut lire/écrire dans le répertoire de stockage :

chmod 755 ./silex/storage
chown $USER:$USER ./silex/storage

Dans Docker, le conteneur s'exécute en tant que root, donc les permissions ne posent généralement pas de problème.

Voir aussi

• Configuration serveur
• Connecteurs de publication
• Publier sur GitLab — Flux de publication