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

이미지 파일은 사용되는 맥락에 맞춰 가독성을 유지해야 합니다. 흰색 페이지에서는 잘 보이는 어두운 로고도 어두운 상단 바에서는 잘 보이지 않을 수 있으므로, 밝은 로고와 어두운 로고 버전을 따로 제공하는 것이 유용합니다. 또한 로그인 컨트롤 뒤의 배경은 비교적 단순하게 유지하세요. 브랜딩은 가독성을 저해하지 않으면서 브랜드 인지도를 높여야 합니다.

2단계: 브랜드 이름, 로고 경로, 파비콘 및 로그인 배경을 정의합니다.

테마 JSON 파일은 사용자 정의의 핵심입니다. 이 common섹션에는 이름과 슬로건과 같은 공통 브랜드 텍스트가 포함되어 있습니다. 아래에서 기본 웹 로고와 로그인 배경을 정의할 수 있습니다. ownCloud의 공식 스키마에서는 , , 에 clients.web.defaults대해 각각 별도의 로고 키를 사용합니다 .topbarfaviconlogin

테마 파일의 브랜딩 부분을 에디터 스타일로 보여주는 그림입니다. 아래 예시에 나와 있는 객체 구조를 참고하여 그림을 복사 붙여넣기 방식으로 사용하지 마십시오.

최소한의 시작점은 아래에 제시된 구조를 기반으로 할 수 있습니다. 웹 서비스가 테마 자산을 노출하는 URL 경로와 경로를 일관되게 유지하십시오.

{
  "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": []
    }
  }
}

JSON 파서가 파일을 허용한다고 해서 모든 키를 안전하게 생략할 수 있다고 가정하지 마십시오. ownCloud는 일부 필수 테마 키가 런타임에 삽입되지만, 구문적으로 유효한 테마라도 의미적으로는 잘못될 수 있다고 지적합니다. 좋은 프로덕션 환경 구축 방법은 실제로 사용하는 Infinite Scale 버전에 포함된 테마 템플릿을 기반으로 필요한 브랜딩 변경만 하고 나머지 구조는 해당 릴리스 버전에 맞춰 유지하는 것입니다.

3단계: 디자인 토큰을 사용하여 테마 색상을 변경합니다.

색상 사용자 지정은 테마 항목 아래에 있어야 합니다 clients.web.themes. 각 테마는 `<head>` 태그를 통해 어두운 테마인지 여부를 나타내고 isDark, 사람이 읽을 수 있는 `<head>` 태그를 제공하며 name, 디자인 토큰을 재정의할 수 있습니다. ` colorPalette<head>` 태그는 일반적으로 브랜드 색상을 조정하는 곳입니다.

ownCloud 웹에서 사용되는 색상 토큰 유형의 예입니다. 팔레트를 확장하기 전에 먼저 선택된 색상 세트를 변경하고 대비 및 마우스 오버 상태를 확인하십시오.

가벼운 기업 테마를 원한다면 모든 색상을 바꾸는 대신 소수의 색상만 바꾸는 것부터 시작할 수 있습니다.

{
  "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"
    }
  }
}

중요한 균형점은 일관성과 완벽성 사이의 균형입니다. 일부만 변경하면 swatch-brand-default시각적인 효과는 빠르게 얻을 수 있지만, 마우스 오버, 대비, 사이드바, 테두리, 텍스트 토큰은 여전히 ​​기본 테마를 반영할 수 있습니다. 반면, 테스트 없이 수십 개의 토큰을 재정의하면 가독성이 떨어지는 조합이 발생할 수 있습니다. 대부분의 경우, 브랜드, 기본 색상, 대비, 배경, 텍스트, 테두리 값을 먼저 변경한 다음, 기본값이 디자인과 눈에 띄게 충돌하는 부분만 확장하는 것이 좋습니다.

특히 대비에 주의를 기울이세요. 밝은 브랜드 색상을 선택했다면 흰색 텍스트를 억지로 사용하는 대신 어두운 대비 요소와 함께 사용하세요. 키보드 포커스, 마우스 오버 상태, 비활성화된 컨트롤, 다크 모드(제공하는 경우), 고대비 모드(사용자에게 중요한 경우) 등을 테스트해 보세요.

4단계: 사용자 지정 테마를 마운트하고 ownCloud가 themes.json 파일을 가리키도록 설정합니다.

디렉터리와 JSON 파일이 준비되면 웹 서비스가 이를 읽을 수 있도록 구성합니다. 관련 환경 변수는 두 가지가 있는데 WEB_ASSET_THEMES_PATH, 하나는 ownCloud에 사용자 지정 테마 루트의 위치를 ​​알려주는 변수이고, WEB_UI_THEME_PATH다른 하나는 로드할 테마 JSON 파일을 선택하는 변수입니다.

Docker Compose 스타일을 사용하여 사용자 지정 테마 디렉터리를 마운트하고 ownCloud 웹 테마 환경 변수 두 개를 구성하는 방법을 보여주는 그림입니다. 실제 배포 환경에 맞게 경로를 수정하십시오.

Docker Compose 배포는 다음과 같은 패턴을 사용할 수 있습니다.

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

위의 이미지 태그는 의도적으로 삽입된 자리 표시자입니다. 실제 운영 환경에서는 예제의 자리 표시자를 복사하는 대신 테스트한 정확한 oCIS 버전을 사용하십시오. 환경 또는 마운트된 파일을 변경한 후에는 배포 방법에 따라 해당 oCIS 서비스를 재시작하거나 다시 생성하여 새 구성이 적용되도록 하십시오.

ownCloud는 중요한 대체 동작에 대해 설명합니다. 사용자 지정 테마가 제공되지 않거나 테마 로드에 실패하면 기본 Infinite Scale 테마가 사용됩니다. 이 대체 동작은 경로가 누락되더라도 인터페이스를 사용할 수 없게 되는 것을 방지하기 때문에 유용합니다. 하지만 재시작 후 기본 ownCloud 화면이 표시되는 것은 사용자 지정 테마가 로드되지 않았을 가능성을 나타내는 진단 단서가 될 수 있습니다.

브랜딩이 실제로 로드되었는지 확인하는 방법

로그인 페이지 변경 후에도 점검을 멈추지 마세요. 사용자가 실제로 브랜드를 접하는 모든 부분을 꼼꼼히 확인해야 합니다. 캐시된 콘텐츠가 현재 상태를 가리는 것을 방지하기 위해 새 브라우저 세션이나 시크릿 창에서 사이트를 열어 확인하세요.

• 로그인 페이지에 예상대로 로고와 배경이 사용되는지 확인하십시오.
• 로그인 후 상단 바의 로고가 올바르게 표시되고 배경과 잘 어우러지는지 확인하십시오.
• 사용자 지정 파비콘은 브라우저 탭에서 확인하세요.
• 파일 영역을 열고 기본 버튼, 마우스 오버 시 나타나는 효과, 사이드바 색상, 폴더 아이콘 및 텍스트 대비를 확인하십시오.
• 밝은 테마와 어두운 테마를 모두 제공하는 경우, 두 테마를 전환하여 각각 독립적으로 확인하십시오.
• 넓은 로고가 반응형 상단 바를 가리지 않도록 최소한 하나의 좁은 브라우저 너비를 확인하십시오.

사용자 지정 테마가 표시되지 않을 때

ownCloud의 기본 테마가 여전히 로드됩니다.

먼저 호스트뿐만 아니라 실행 중인 컨테이너 또는 서비스 내부의 경로를 확인해야 합니다. 경로는 WEB_ASSET_THEMES_PATH웹 서비스에서 인식하는 테마 루트를 참조해야 하며, WEB_UI_THEME_PATH실제 JSON 파일도 해당 환경 내에서 참조해야 합니다. 컨테이너에 마운트되지 않은 호스트 경로는 ownCloud에서 읽을 수 없습니다.

JSON 데이터는 로드되지만 이미지가 누락되었습니다.

파일 경로 themes.json, 파일 이름의 대소문자, 그리고 해당 파일이 사용자 지정 테마 디렉터리에 있는지 확인하세요. 브라우저 개발자 도구를 사용하면 잘못된 에셋 요청과 테마 문제를 구분하는 데 도움이 될 수 있습니다. 테마 색상은 로드되지만 로고 하나가 로드되지 않는 경우, 테마 자체는 유효하지만 에셋 경로가 잘못되었을 수 있습니다.

페이지에 브랜드가 적용되었지만 색상이 일관성이 없어 보입니다.

이는 일반적으로 팔레트의 일부만 재정의되었음을 의미합니다. 관련 호버 및 대비 토큰을 추가한 다음 다시 테스트하십시오. 관련 없는 텍스트나 배경 토큰을 광범위하게 변경하여 읽기 어려운 버튼 하나를 해결하지 마십시오. 가장 작고 일관성 있는 변경 사항을 적용하고 인터페이스 전체에서 확인하십시오.

테마가 이전 버전에서는 제대로 작동하지만 업그레이드 후에는 제대로 표시되지 않습니다.

테마 토큰과 프런트엔드 동작은 변경될 수 있습니다. 프로덕션 환경을 업그레이드하기 전에 사용자 지정 테마를 대상 oCIS 릴리스의 템플릿 및 문서와 비교하십시오. ownCloud의 웹 사용자 지정 구성 문서에서는 지원되는 구성/사용자 지정 자산과 완전히 사용자 지정으로 컴파일된 웹 자산을 제공하는 것의 차이점도 설명합니다.

컴파일된 웹 자산을 직접 편집해야 할까요?

일반적으로 일반적인 브랜딩에는 적합하지 않습니다. 지원되는 웹 UI를 유지하면서 이름, 로고, 배경 및 디자인 토큰을 변경하려는 경우 사용자 지정 테마가 더 적합합니다. 완전히 사용자 지정으로 컴파일된 에셋은 테마 또는 지원되는 에셋 오버라이드로는 표현할 수 없는, 완전히 수정된 프런트엔드를 개발하거나 배포하는 경우에만 의미가 있습니다. 이러한 접근 방식은 ownCloud 웹의 향후 변경 사항과 사용자 지정 빌드의 호환성을 유지해야 하므로 유지 관리 비용이 더 높습니다.

실용적인 생산 체크리스트

• 사용자 지정 테마 파일은 기본 애플리케이션 디렉터리 외부에 보관하십시오.
• 설치된 oCIS 버전에 대해 문서화된 테마 구조부터 시작하십시오.
• 밝은 표면과 어두운 표면에 각각 다른 로고 변형을 사용해야 할 경우, 별도의 로고 변형을 사용하십시오.
• 먼저 호버 값과 대비 값을 포함하여 특정 디자인 토큰 세트를 재정의합니다.
• 가능하면 테마 디렉토리를 읽기 전용으로 마운트하십시오.
• WEB_ASSET_THEMES_PATH와 를 모두 WEB_UI_THEME_PATH서비스 내부에서 볼 수 있는 경로로 설정하십시오 .
• 배포 변경 후 웹/oCIS 서비스를 다시 시작하거나 다시 생성하십시오.
• 로그인 화면, 상단 바, 파비콘, 파일 영역, 반응형 레이아웃, 그리고 어두운/고대비 테마 등 제공하는 모든 테마를 확인하십시오.
• ownCloud Infinite Scale의 주요 업그레이드를 진행하기 전에 테마를 다시 테스트하십시오.

현재 Infinite Scale 배포 환경에서 이 테마 파일 접근 방식은 관리자에게 애플리케이션 코드와 시각적 아이덴티티를 명확하게 분리할 수 있는 방법을 제공합니다. 핵심은 테마를 버전 관리되는 배포 자산으로 취급하는 것입니다. 즉, ownCloud 릴리스에서 지원하는 스키마를 사용하고, 이미지 경로를 예측 가능하게 유지하며, 프런트엔드에서 임의로 수정하는 대신 디자인 토큰을 통해 색상을 변경하고, 한 화면에서만 성공 여부를 판단하는 대신 전체 웹 인터페이스에서 결과를 검증해야 합니다.