How to Customize ownCloud Web UI Branding and Theme Colors

The most reliable way to customize the current ownCloud Web interface is to create a supported theme JSON file and point ownCloud Infinite Scale to that theme. You do not need to rebuild the Web frontend just to change the brand name, logos, favicon, login background, or common interface colors. In the current Infinite Scale theming model, those elements are supplied through a theme definition, while design tokens control colors and other visual values.

This guide is written for ownCloud Infinite Scale (oCIS) and its modern ownCloud Web frontend. It is not a guide for the older ownCloud Server 10/11 PHP theming system, which uses an app-based theme structure and different configuration. ownCloud's stable Infinite Scale 8.2 documentation and the 9.0 development documentation both describe the same runtime approach: provide a custom themes directory with WEB_ASSET_THEMES_PATH, then select a theme JSON file with WEB_UI_THEME_PATH. See the official ownCloud Web custom theming documentation.

What you can customize without rebuilding ownCloud Web

A normal organization theme can cover the visual changes most administrators actually need. The theme JSON can define the product name and slogan, paths to logos and a favicon, the login-page background, and Web design tokens such as brand, primary, background, text, border, and file-type colors. This is preferable to editing compiled frontend files because the theme remains a separate deployment asset and can be managed alongside your server configuration.

Step 1: Create a separate theme directory and assets folder

Start by keeping your custom theme separate from the built-in ownCloud assets. A simple layout is a theme directory containing themes.json plus an assets folder for your logos, favicon, and login image. The exact host path is your choice; what matters is that the directory is mounted or otherwise exposed to the oCIS Web service through WEB_ASSET_THEMES_PATH.

Example file layout for a custom ownCloud Web theme. The theme definition and image assets are kept together in a dedicated directory.

For example, a host-side structure could look like this:

/srv/owncloud/themes/
└── acme/
    ├── themes.json
    └── assets/
        ├── logo.svg
        ├── logo-white.svg
        ├── favicon.png
        └── login-background.jpg

Utilisez des images qui restent lisibles quel que soit leur contexte. Un logo sombre, même sur fond blanc, risque de se fondre dans une barre supérieure sombre ; il est donc souvent judicieux de proposer des versions claires et sombres. Veillez également à ce que l’arrière-plan de la page de connexion reste relativement simple. L’identité visuelle doit renforcer la reconnaissance sans nuire à la lisibilité.

Étape 2 : Définir le nom de la marque, les tracés du logo, le favicon et l’arrière-plan de connexion

Le fichier JSON du thème est au cœur de la personnalisation. Cette commonsection contient les éléments de marque communs, tels que le nom et le slogan. Sous clients.web.defaults, vous pouvez définir les logos Web par défaut et l'arrière-plan de connexion. Le schéma documenté d'ownCloud utilise des clés de logo distinctes pour topbar, faviconet login.

Illustration, de type éditeur, de la partie relative à l'identité visuelle d'un fichier de thème. Utilisez la structure d'objet documentée dans l'exemple ci-dessous plutôt que de considérer l'illustration comme un code à copier-coller.

Vous pouvez commencer par la structure ci-dessous. Veillez à ce que les chemins d'accès correspondent à l'URL par laquelle le service Web expose les ressources de votre thème :

{
  "common": {
    "name": "Acme Cloud",
    "slogan": "Your files. Your workspace.",
    "logo": "themes/acme/assets/logo.svg",
    "urls": {
      "accessDeniedHelp": "",
      "imprint": "",
      "privacy": "",
      "accessibilityStatement": "",
      "universalAccessEasyLanguage": "",
      "universalAccessSignLanguage": ""
    }
  },
  "clients": {
    "android": {},
    "desktop": {},
    "ios": {},
    "web": {
      "defaults": {
        "appBanner": {},
        "logo": {
          "topbar": "themes/acme/assets/logo-white.svg",
          "favicon": "themes/acme/assets/favicon.png",
          "login": "themes/acme/assets/logo-white.svg"
        },
        "loginPage": {
          "backgroundImg": "themes/acme/assets/login-background.jpg"
        },
        "icons": {
          "universalAccess": "",
          "universalAccessEasyLanguage": "",
          "universalAccessSignLanguage": ""
        }
      },
      "themes": []
    }
  }
}

Ne présumez pas que toutes les clés peuvent être omises sans risque simplement parce que l'analyseur JSON accepte le fichier. ownCloud indique que certaines clés de thème obligatoires sont injectées à l'exécution, mais un thème syntaxiquement valide peut néanmoins être sémantiquement incorrect. En production, il est recommandé de partir du modèle de thème fourni avec la version d'Infinite Scale que vous utilisez, d'apporter uniquement les modifications de marque nécessaires et de conserver le reste de la structure conforme à cette version.

Étape 3 : Modifier les couleurs du thème à l’aide de jetons de conception

La personnalisation des couleurs se trouve dans une entrée de thème sous clients.web.themes. Chaque thème peut indiquer s'il est sombre avec isDark, fournir une description lisible nameet remplacer les jetons de conception. C'est colorPaletteici que les couleurs visibles de la marque sont généralement ajustées.

Exemple des types de jetons de couleur utilisés par ownCloud Web. Modifiez d'abord un ensemble sélectionné, puis vérifiez le contraste et les états de survol avant d'étendre la palette.

Pour un thème d'entreprise discret, vous pourriez commencer par un petit ensemble de jetons au lieu de changer toutes les couleurs disponibles :

{
  "isDark": false,
  "name": "Acme Light",
  "logo": {
    "topbar": "themes/acme/assets/logo-white.svg",
    "favicon": "themes/acme/assets/favicon.png",
    "login": "themes/acme/assets/logo-white.svg"
  },
  "designTokens": {
    "colorPalette": {
      "background-default": "#ffffff",
      "background-sidebar": "#f5f7fa",
      "background-hover": "#eef4fb",
      "border": "#d8e0e8",
      "swatch-brand-default": "#176B87",
      "swatch-brand-hover": "#12556C",
      "swatch-brand-contrast": "#ffffff",
      "swatch-primary-default": "#176B87",
      "swatch-primary-hover": "#12556C",
      "swatch-primary-contrast": "#ffffff",
      "text-default": "#102A33",
      "text-inverse": "#ffffff",
      "text-muted": "#526873",
      "icon-folder": "#176B87"
    }
  }
}

Le compromis essentiel réside dans l'équilibre entre cohérence et exhaustivité. Modifier uniquement les éléments par défaut swatch-brand-defaultpeut donner un résultat visuel immédiat, mais les propriétés de survol, de contraste, de barre latérale, de bordure et de texte peuvent encore refléter le thème par défaut. À l'inverse, la redéfinition de dizaines d'éléments sans test préalable peut créer des combinaisons illisibles. Pour la plupart des déploiements, commencez par les valeurs de marque, de couleur principale, de contraste, d'arrière-plan, de texte et de bordure, puis étendez-les uniquement lorsque les valeurs par défaut entrent en conflit visible avec votre design.

Portez une attention particulière au contraste. Si vous optez pour une couleur claire pour votre marque, associez-la à un élément contrasté foncé plutôt que d'y superposer du texte blanc. Testez la gestion du focus clavier, les états de survol, les commandes désactivées, le mode sombre (le cas échéant) et les modes à contraste élevé (s'ils sont importants pour vos utilisateurs).

Étape 4 : Montez le thème personnalisé et configurez ownCloud pour qu’il pointe vers themes.json.

Une fois le répertoire et le fichier JSON prêts, configurez le service Web pour qu'il puisse les lire. Les deux variables d'environnement pertinentes sont : `customthemeroot` WEB_ASSET_THEMES_PATH, qui indique à ownCloud l'emplacement du répertoire racine du thème personnalisé, et WEB_UI_THEME_PATH`theme.jsonfile`, qui sélectionne le fichier JSON du thème à charger.

Illustration, au format Docker Compose, du montage d'un répertoire de thème personnalisé et de la configuration des deux variables d'environnement de thème web ownCloud. Adaptez les chemins à votre déploiement.

Un déploiement Docker Compose pourrait utiliser un modèle comme celui-ci :

services:
  ocis:
    image: owncloud/ocis:<your-tested-version>
    environment:
      WEB_ASSET_THEMES_PATH: /etc/ocis/themes
      WEB_UI_THEME_PATH: /etc/ocis/themes/acme/themes.json
    volumes:
      - ./themes:/etc/ocis/themes:ro

L'image ci-dessus est un exemple. En production, utilisez la version exacte d'oCIS que vous avez testée plutôt que de copier une image d'exemple. Après toute modification de l'environnement ou des fichiers montés, redémarrez ou recréez le service oCIS concerné selon votre méthode de déploiement afin que la nouvelle configuration soit prise en compte.

ownCloud documente un comportement de repli important : si aucun thème personnalisé n’est fourni, ou si le chargement du thème échoue, le thème standard Infinite Scale est utilisé. Ce comportement de repli est utile car l’absence d’un chemin d’accès ne rend pas nécessairement l’interface inutilisable. Cependant, cela signifie également que l’affichage de l’apparence par défaut d’ownCloud après un redémarrage peut indiquer que votre thème personnalisé n’a pas été chargé.

Comment vérifier que la marque a bien été chargée ?

Ne vous arrêtez pas à la modification de la page de connexion. Une vérification complète doit couvrir tous les endroits où les utilisateurs verront votre marque. Ouvrez le site dans une nouvelle session de navigateur ou une fenêtre de navigation privée afin de réduire le risque qu'une ressource en cache masque l'état actuel.

• Vérifiez que la page de connexion utilise bien le logo et l'arrière-plan attendus.
• Après vous être connecté(e), vérifiez que le logo de la barre supérieure est correct et reste lisible sur son fond.
• Consultez l'onglet de votre navigateur pour trouver l'icône personnalisée.
• Ouvrez la zone de fichiers et vérifiez les boutons principaux, les états de survol, les couleurs de la barre latérale, les icônes des dossiers et le contraste du texte.
• Si vous proposez des thèmes clair et sombre, alternez entre eux et vérifiez-les indépendamment.
• Vérifiez au moins une largeur de navigateur étroite afin qu'un logo large n'encombre pas la barre supérieure adaptative.

Lorsque le thème personnalisé n'apparaît pas

Le thème ownCloud par défaut se charge toujours.

Vérifiez d'abord les chemins d'accès à l'intérieur du conteneur ou du service en cours d'exécution, et non pas seulement sur l'hôte. WEB_ASSET_THEMES_PATHLe chemin doit pointer vers la racine du thème telle qu'elle est vue par le service Web, et WEB_UI_THEME_PATHdoit pointer vers le fichier JSON correspondant dans cet environnement. Un chemin hôte qui n'a jamais été monté dans le conteneur ne peut pas être lu par ownCloud.

Le fichier JSON se charge, mais une image est manquante.

Vérifiez le chemin d'accès à la ressource themes.json(en respectant la casse) et assurez-vous que le fichier existe bien dans le répertoire des thèmes personnalisés. Les outils de développement de votre navigateur peuvent vous aider à distinguer une requête de ressource incorrecte d'un problème de thème. Si les couleurs du thème s'affichent mais qu'un logo ne s'affiche pas, le thème lui-même est peut-être valide, mais le chemin d'accès à cette ressource est erroné.

La page est bien identifiée, mais les couleurs semblent incohérentes.

Cela signifie généralement que seule une partie de la palette a été modifiée. Ajoutez les éléments de survol et de contraste correspondants, puis testez à nouveau. Ne corrigez pas un bouton illisible en modifiant globalement des éléments de texte ou d'arrière-plan non pertinents ; apportez la modification la plus petite et cohérente possible et vérifiez-la sur l'ensemble de l'interface.

Un thème fonctionne correctement sur une version, mais son apparence peut être incorrecte après une mise à jour.

Les jetons de thème et le comportement de l'interface utilisateur peuvent évoluer. Avant de mettre à niveau un environnement de production, comparez votre thème personnalisé avec le modèle et la documentation de la version oCIS cible. La documentation de configuration Web personnalisée d'ownCloud explique également la différence entre les ressources de configuration/personnalisées prises en charge et la fourniture de ressources Web compilées entièrement personnalisées.

Devriez-vous plutôt modifier les ressources Web compilées ?

Généralement déconseillé pour une stratégie de marque classique. Un thème personnalisé est plus adapté si votre objectif est de modifier les noms, logos, arrière-plans et éléments graphiques tout en conservant une interface utilisateur web compatible. Les ressources compilées entièrement personnalisées ne sont pertinentes que si vous développez ou distribuez une interface utilisateur véritablement modifiée, qui ne peut être reproduite par le biais de thèmes ou de substitutions de ressources standard. Cette approche engendre des coûts de maintenance plus élevés, car il vous incombe de garantir la compatibilité de votre version personnalisée avec les futures mises à jour d'ownCloud Web.

Liste de contrôle pratique pour la production

• Conservez les fichiers de thème personnalisés en dehors des répertoires intégrés de l'application.
• Commencez par la structure du thème documentée pour votre version d'oCIS installée.
• Utilisez des variantes de logo distinctes lorsque les surfaces claires et foncées l'exigent.
• Commencez par remplacer un ensemble ciblé de jetons de conception, notamment les valeurs de survol et de contraste.
• Montez le répertoire du thème en lecture seule lorsque cela est possible.
• Définissez les deux chemins WEB_ASSET_THEMES_PATHsur WEB_UI_THEME_PATHdes valeurs visibles à l'intérieur du service.
• Redémarrez ou recréez le service Web/oCIS après les modifications de déploiement.
• Vérifiez la connexion, la barre supérieure, le favicon, la zone de fichiers, la mise en page adaptative et tous les thèmes sombres/à contraste élevé que vous utilisez.
• Testez à nouveau le thème avant chaque mise à jour majeure d'ownCloud Infinite Scale.

Pour les déploiements Infinite Scale actuels, cette approche par fichier de thème offre aux administrateurs une séparation claire entre le code applicatif et l'identité visuelle. L'essentiel est de considérer le thème comme une ressource de déploiement versionnée : utilisez le schéma pris en charge par votre version ownCloud, assurez-vous que les chemins d'accès aux images soient prévisibles, modifiez les couleurs via des jetons de conception plutôt que par des modifications ponctuelles de l'interface utilisateur, et vérifiez le résultat sur l'ensemble de l'interface Web au lieu de vous fier à un seul écran.