From 9c792ba88eb362ea694097b37bb2b9f125ad0868 Mon Sep 17 00:00:00 2001
From: Alex Culea <195758113+alexculealt@users.noreply.github.com>
Date: Mon, 16 Feb 2026 11:03:10 +0200
Subject: [PATCH 1/2] (#16) Allow customization of Admin panel colors and logo

- Add settings model and DB schema
- Implement new LogoUploader to handle admin panel logo customization
- Implement appearance setting edit & logo upload UI
---
 .gitignore                                    |   2 +
 Gemfile.lock                                  |   5 +
 app/controllers/admin/settings_controller.rb  | 107 ++++
 app/controllers/application_controller.rb     |   8 +
 .../components/admin/ImageUpload.jsx          | 503 ++++++++++++++++++
 .../components/admin/Initializer.jsx          |  11 +
 app/models/setting.rb                         |  72 +++
 app/services/s3_service.rb                    |  10 +
 app/uploaders/image_uploader.rb               |  41 ++
 app/views/admin/settings/edit.html.erb        |  15 +
 app/views/admin/settings/edit/_color.html.erb |   7 +
 app/views/admin/settings/edit/_image.html.erb |   7 +
 app/views/admin/settings/index.html.erb       |  74 +++
 app/views/admin/settings/show/_color.html.erb |   7 +
 app/views/admin/settings/show/_image.html.erb |  23 +
 app/views/shared/_header.html.erb             |  35 +-
 config/initializers/lcms_constants.rb         |  20 +
 config/locales/admin/en.yml                   |  51 +-
 config/routes.rb                              |   6 +
 db/migrate/20260219081358_create_settings.rb  |  11 +
 db/schema.rb                                  |  10 +-
 spec/factories/settings.rb                    |   8 +
 spec/models/setting_spec.rb                   | 156 ++++++
 spec/requests/admin/settings_spec.rb          | 222 ++++++++
 24 files changed, 1404 insertions(+), 7 deletions(-)
 create mode 100644 app/controllers/admin/settings_controller.rb
 create mode 100644 app/javascript/components/admin/ImageUpload.jsx
 create mode 100644 app/models/setting.rb
 create mode 100644 app/uploaders/image_uploader.rb
 create mode 100644 app/views/admin/settings/edit.html.erb
 create mode 100644 app/views/admin/settings/edit/_color.html.erb
 create mode 100644 app/views/admin/settings/edit/_image.html.erb
 create mode 100644 app/views/admin/settings/index.html.erb
 create mode 100644 app/views/admin/settings/show/_color.html.erb
 create mode 100644 app/views/admin/settings/show/_image.html.erb
 create mode 100644 db/migrate/20260219081358_create_settings.rb
 create mode 100644 spec/factories/settings.rb
 create mode 100644 spec/models/setting_spec.rb
 create mode 100644 spec/requests/admin/settings_spec.rb

diff --git a/.gitignore b/.gitignore
index fd721f2..7ea21b9 100644
--- a/.gitignore
+++ b/.gitignore
@@ -32,6 +32,8 @@
 !/tmp/storage/.keep
 
 /public/assets
+/public/uploads/**
+!/public/uploads/**/.keep
 
 # Ignore key files for decrypting credentials and more.
 /config/*.key
diff --git a/Gemfile.lock b/Gemfile.lock
index d0c1cad..11d9db0 100644
--- a/Gemfile.lock
+++ b/Gemfile.lock
@@ -248,6 +248,7 @@ GEM
     ffi (1.17.2-aarch64-linux-musl)
     ffi (1.17.2-arm-linux-gnu)
     ffi (1.17.2-arm-linux-musl)
+    ffi (1.17.2-arm64-darwin)
     ffi (1.17.2-x86_64-linux-gnu)
     ffi (1.17.2-x86_64-linux-musl)
     fileutils (1.8.0)
@@ -422,6 +423,8 @@ GEM
       racc (~> 1.4)
     nokogiri (1.19.0-arm-linux-musl)
       racc (~> 1.4)
+    nokogiri (1.19.0-arm64-darwin)
+      racc (~> 1.4)
     nokogiri (1.19.0-x86_64-linux-gnu)
       racc (~> 1.4)
     nokogiri (1.19.0-x86_64-linux-musl)
@@ -715,6 +718,7 @@ GEM
     thread_safe (0.3.6)
     thruster (0.1.16)
     thruster (0.1.16-aarch64-linux)
+    thruster (0.1.16-arm64-darwin)
     thruster (0.1.16-x86_64-linux)
     tilt (2.7.0)
     timeout (0.6.0)
@@ -772,6 +776,7 @@ PLATFORMS
   aarch64-linux-musl
   arm-linux-gnu
   arm-linux-musl
+  arm64-darwin-25
   x86_64-linux
   x86_64-linux-gnu
   x86_64-linux-musl
diff --git a/app/controllers/admin/settings_controller.rb b/app/controllers/admin/settings_controller.rb
new file mode 100644
index 0000000..3e8bf47
--- /dev/null
+++ b/app/controllers/admin/settings_controller.rb
@@ -0,0 +1,107 @@
+module Admin
+  class SettingsController < AdminController
+    before_action :load_all_settings, only: %i(index update)
+
+    def index; end
+
+    def update
+      SETTINGS.each do |group, types|
+        permitted_keys = types.keys.map(&:to_s)
+        processed_params = process_image_uploads(params)
+        new_settings = processed_params.permit(permitted_keys).to_h
+        changes = new_settings.select { |key, value| @all_settings[group][key.to_sym] != value }
+
+        next unless changes.any?
+
+        current = Setting.get(group) || {}
+        Setting.set(group, current.merge(changes))
+      end
+
+      redirect_to admin_settings_path, notice: t("admin.settings.updated.success")
+    end
+
+    def destroy
+      key = params[:key]
+      group = group_for_key(key)
+      return redirect_to admin_settings_path unless group
+
+      delete_old_image_if_present(group, key) if image_setting?(group, key)
+      Setting.unset_within(group, key)
+      redirect_to admin_settings_path, notice: t("admin.settings.deleted.success"), status: :see_other
+    end
+
+    def upload_image
+      return head :unprocessable_entity unless params[:image].respond_to?(:tempfile)
+
+      uploader = ImageUploader.new
+      uploader.store!(params[:image])
+      render json: { url: uploader.url }
+    rescue CarrierWave::IntegrityError, CarrierWave::ProcessingError => e
+      render json: { error: e.message }, status: :unprocessable_entity
+    end
+
+    private
+
+    def load_all_settings
+      @all_settings = Setting.get_multiple(SETTINGS.keys, include_defaults: true)
+    end
+
+    def group_for_key(key)
+      SETTINGS.find { |_group, types| types.key?(key.to_sym) }&.first
+    end
+
+    def process_image_uploads(params)
+      image_keys = SETTINGS.flat_map { |_group, types| types.select { |_k, v| v == :image }.keys }
+      modified = params.to_unsafe_h
+
+      image_keys.each do |key|
+        next unless params[key].respond_to?(:tempfile)
+
+        uploader = ImageUploader.new
+        uploader.store!(params[key])
+        modified[key] = uploader.url
+      end
+
+      ActionController::Parameters.new(modified)
+    end
+
+    def image_setting?(group, key)
+      key.present? && SETTINGS.dig(group, key.to_sym) == :image
+    end
+
+    def delete_old_image_if_present(group, setting_key)
+      settings = Setting.get(group, include_defaults: true)
+      old_url = settings[setting_key.to_sym]
+      return if old_url.blank?
+
+      if stored_locally?(old_url)
+        delete_local_image(old_url)
+      elsif stored_on_s3?(old_url)
+        delete_s3_image(old_url)
+      end
+    rescue StandardError => e
+      Rails.logger.warn "Failed to delete old image: #{e.message}"
+    end
+
+    def stored_locally?(url)
+      url.to_s.start_with?("/uploads/settings/")
+    end
+
+    def stored_on_s3?(url)
+      url.to_s.include?("s3") || url.to_s.include?("amazonaws")
+    end
+
+    def delete_local_image(url)
+      path = Rails.root.join("public", url.to_s.delete_prefix("/"))
+      FileUtils.rm_f(path) if path.exist?
+    end
+
+    def delete_s3_image(url)
+      uri = URI.parse(url)
+      key = URI.decode_www_form_component(uri.path.delete_prefix("/"))
+      return unless key.start_with?("uploads/settings/")
+
+      S3Service.delete_object(key)
+    end
+  end
+end
diff --git a/app/controllers/application_controller.rb b/app/controllers/application_controller.rb
index 52f7c16..ef08b53 100644
--- a/app/controllers/application_controller.rb
+++ b/app/controllers/application_controller.rb
@@ -10,6 +10,8 @@ class ApplicationController < ActionController::Base
 
   before_action :authenticate_user!, unless: :pdf_request?
 
+  before_action :load_header_settings
+
   before_action :configure_permitted_parameters, if: :devise_controller?
 
   rescue_from ActiveRecord::RecordNotFound do
@@ -28,6 +30,12 @@ def configure_permitted_parameters
     devise_parameter_sanitizer.permit(:sign_up, keys: [:access_code])
   end
 
+  def load_header_settings
+    @header_settings = Rails.cache.fetch(Setting.cache_key_for(:appearance, include_defaults: true)) do
+      Setting.get(:appearance, include_defaults: true)
+    end
+  end
+
   private
 
   def after_sign_in_path_for(resource_or_scope)
diff --git a/app/javascript/components/admin/ImageUpload.jsx b/app/javascript/components/admin/ImageUpload.jsx
new file mode 100644
index 0000000..fe4ac98
--- /dev/null
+++ b/app/javascript/components/admin/ImageUpload.jsx
@@ -0,0 +1,503 @@
+import React from "react";
+import PropTypes from "prop-types";
+import { Modal } from "bootstrap";
+
+const MODAL_STYLES = {
+  dialog: { width: "66.67vw", maxWidth: 600 },
+  content: { height: 400 },
+  body: { overflow: "auto", minHeight: 0 }
+};
+
+const isImageFile = (file) => file?.type?.startsWith("image/");
+
+class DropZone extends React.Component {
+  handleKeyDown = (e) => {
+    const { isDisabled, onSelect } = this.props;
+    if (!isDisabled && (e.key === "Enter" || e.key === " ")) {
+      e.preventDefault();
+      onSelect();
+    }
+  };
+
+  render() {
+    const {
+      isDisabled,
+      isDragOver,
+      onSelect,
+      onDragOver,
+      onDragLeave,
+      onDrop,
+      dragDropHint,
+      pasteHint,
+      ariaLabel,
+      uploading,
+      uploadPending
+    } = this.props;
+
+    const style = {
+      minHeight: 140,
+      padding: 24,
+      border: "2px dashed",
+      borderRadius: 8,
+      display: "flex",
+      flexDirection: "column",
+      alignItems: "center",
+      justifyContent: "center",
+      gap: 8,
+      cursor: isDisabled ? "not-allowed" : "pointer",
+      opacity: isDisabled ? 0.6 : 1,
+      transition: "border-color 0.2s, background-color 0.2s",
+      ...(isDragOver
+        ? { borderColor: "var(--bs-primary)", backgroundColor: "rgba(var(--bs-primary-rgb), 0.08)" }
+        : { borderColor: "var(--bs-border-color)", backgroundColor: "var(--bs-light)" })
+    };
+
+    return (
+      <div
+        role="button"
+        tabIndex={isDisabled ? -1 : 0}
+        className="mb-3"
+        style={style}
+        onDragOver={isDisabled ? undefined : onDragOver}
+        onDragLeave={isDisabled ? undefined : onDragLeave}
+        onDrop={isDisabled ? undefined : onDrop}
+        onClick={isDisabled ? undefined : onSelect}
+        onKeyDown={this.handleKeyDown}
+        aria-label={ariaLabel}
+        aria-disabled={isDisabled}
+      >
+        {uploadPending ? (
+          <div className="spinner-border spinner-border-sm" role="status">
+            <span className="visually-hidden">{uploading}</span>
+          </div>
+        ) : (
+          <>
+            <i className="bi bi-cloud-arrow-up fs-2 text-muted" aria-hidden="true" />
+            <span className="text-muted small">{dragDropHint}</span>
+            <span className="text-muted small">{pasteHint}</span>
+          </>
+        )}
+      </div>
+    );
+  }
+}
+
+DropZone.propTypes = {
+  isDisabled: PropTypes.bool.isRequired,
+  isDragOver: PropTypes.bool.isRequired,
+  onSelect: PropTypes.func.isRequired,
+  onDragOver: PropTypes.func.isRequired,
+  onDragLeave: PropTypes.func.isRequired,
+  onDrop: PropTypes.func.isRequired,
+  dragDropHint: PropTypes.string.isRequired,
+  pasteHint: PropTypes.string.isRequired,
+  ariaLabel: PropTypes.string.isRequired
+};
+
+class ImageUpload extends React.Component {
+  constructor(props) {
+    super(props);
+    this.previewModalRef = React.createRef();
+    this.uploadModalRef = React.createRef();
+    this.fileInputRef = React.createRef();
+    this.previewModalInstance = null;
+    this.uploadModalInstance = null;
+    this.state = {
+      currentUrl: props.imageUrl || "",
+      uploadPending: false,
+      uploadError: null,
+      uploadComplete: false,
+      isDragOver: false,
+      wrongFileTypeWarning: null
+    };
+  }
+
+  componentDidMount() {
+    if (this.previewModalRef.current) {
+      this.previewModalInstance = new Modal(this.previewModalRef.current);
+    }
+    if (this.uploadModalRef.current) {
+      this.uploadModalInstance = new Modal(this.uploadModalRef.current);
+      this.uploadModalRef.current.addEventListener("show.bs.modal", this.handleUploadModalShow);
+      this.uploadModalRef.current.addEventListener("shown.bs.modal", this.handleUploadModalShown);
+      this.uploadModalRef.current.addEventListener("hide.bs.modal", this.handleUploadModalHide);
+      this.uploadModalRef.current.addEventListener("hidden.bs.modal", this.handleUploadModalHidden);
+    }
+    this.syncHiddenInput();
+    const form = this.getForm();
+    if (form) form.addEventListener("submit", this.syncHiddenInput);
+  }
+
+  componentWillUnmount() {
+    const form = this.getForm();
+    if (form) form.removeEventListener("submit", this.syncHiddenInput);
+    document.removeEventListener("paste", this.handlePaste);
+    if (this.uploadModalRef.current) {
+      this.uploadModalRef.current.removeEventListener("show.bs.modal", this.handleUploadModalShow);
+      this.uploadModalRef.current.removeEventListener("shown.bs.modal", this.handleUploadModalShown);
+      this.uploadModalRef.current.removeEventListener("hide.bs.modal", this.handleUploadModalHide);
+      this.uploadModalRef.current.removeEventListener("hidden.bs.modal", this.handleUploadModalHidden);
+    }
+    this.previewModalInstance?.dispose();
+    this.uploadModalInstance?.dispose();
+  }
+
+  componentDidUpdate(prevProps, prevState) {
+    if (prevState.currentUrl !== this.state.currentUrl) {
+      this.syncHiddenInput();
+    }
+  }
+
+  getForm = () => {
+    const { formId } = this.props;
+    return formId ? document.getElementById(formId) : null;
+  };
+
+  syncHiddenInput = () => {
+    const { formId, fieldName } = this.props;
+    if (!formId || !fieldName) return;
+    const input = document.querySelector(`input[form="${formId}"][name="${fieldName}"]`);
+    if (input) input.value = this.state.currentUrl || "";
+  };
+
+  notifyFormChange = () => {
+    const form = this.getForm();
+    if (form) form.dispatchEvent(new Event("change", { bubbles: true }));
+  };
+
+  handleUploadModalShow = () => {
+    this.setState({ uploadComplete: false, wrongFileTypeWarning: null, uploadError: null });
+  };
+
+  handleUploadModalShown = () => {
+    document.addEventListener("paste", this.handlePaste);
+  };
+
+  handleUploadModalHide = (e) => {
+    if (this.state.uploadPending) e.preventDefault();
+  };
+
+  handleUploadModalHidden = () => {
+    document.removeEventListener("paste", this.handlePaste);
+    this.setState({ isDragOver: false, uploadComplete: false, wrongFileTypeWarning: null });
+  };
+
+  showWrongFileTypeWarning = () => {
+    const { wrongFileType } = this.props;
+    this.setState({ wrongFileTypeWarning: wrongFileType });
+  };
+
+  handlePaste = (e) => {
+    if (this.state.uploadComplete) return;
+    const file = e.clipboardData?.files?.[0];
+    if (file) {
+      e.preventDefault();
+      if (isImageFile(file)) {
+        this.uploadFile(file);
+      } else {
+        this.showWrongFileTypeWarning();
+      }
+    }
+  };
+
+  handleFileChange = (e) => {
+    const file = e.target.files?.[0];
+    if (file) {
+      if (isImageFile(file)) {
+        this.uploadFile(file);
+      } else {
+        this.showWrongFileTypeWarning();
+      }
+      e.target.value = "";
+    }
+  };
+
+  handleDragOver = (e) => {
+    e.preventDefault();
+    e.stopPropagation();
+    if (!this.state.uploadPending && !this.state.uploadComplete) {
+      this.setState({ isDragOver: true });
+    }
+    e.dataTransfer.dropEffect = "copy";
+  };
+
+  handleDragLeave = (e) => {
+    e.preventDefault();
+    e.stopPropagation();
+    this.setState({ isDragOver: false });
+  };
+
+  handleDrop = (e) => {
+    e.preventDefault();
+    e.stopPropagation();
+    this.setState({ isDragOver: false });
+    if (this.state.uploadPending || this.state.uploadComplete) return;
+    const file = e.dataTransfer?.files?.[0];
+    if (file) {
+      if (isImageFile(file)) {
+        this.uploadFile(file);
+      } else {
+        this.showWrongFileTypeWarning();
+      }
+    }
+  };
+
+  uploadFile = (file) => {
+    const { uploadUrl, fileFieldName = "image" } = this.props;
+    if (!uploadUrl) return;
+
+    this.setState({ uploadPending: true, uploadError: null, wrongFileTypeWarning: null });
+
+    const formData = new FormData();
+    formData.append(fileFieldName, file);
+
+    const csrfToken = document.querySelector('meta[name="csrf-token"]')?.getAttribute("content");
+
+    fetch(uploadUrl, {
+      method: "POST",
+      headers: {
+        "X-CSRF-Token": csrfToken,
+        "Accept": "application/json"
+      },
+      body: formData
+    })
+      .then((response) => {
+        if (!response.ok) {
+          return response
+            .json()
+            .then((data) => { throw new Error(data.error || `Upload failed (${response.status})`); })
+            .catch(() => { throw new Error(`Upload failed (${response.status})`); });
+        }
+        return response.json();
+      })
+      .then((data) => {
+        this.setState({
+          currentUrl: data.url,
+          uploadPending: false,
+          uploadError: null,
+          uploadComplete: true
+        });
+        this.notifyFormChange();
+      })
+      .catch((err) => {
+        this.setState({ uploadPending: false, uploadError: err.message });
+      });
+  };
+
+  showFilePicker = () => this.fileInputRef.current?.click();
+
+  showPreviewModal = () => this.previewModalInstance?.show();
+
+  showUploadModal = () => this.uploadModalInstance?.show();
+
+  closeUploadModal = () => this.uploadModalInstance?.hide();
+
+  renderPreviewModal() {
+    const { useResetInfo, imagePreviewTitle, close, fullSizeAlt } = this.props;
+    const displayUrl = this.state.currentUrl || this.props.imageUrl;
+
+    return (
+      <div
+        className="modal fade"
+        ref={this.previewModalRef}
+        tabIndex={-1}
+        aria-labelledby="imagePreviewModalLabel"
+        aria-hidden="true"
+      >
+        <div className="modal-dialog modal-dialog-centered" style={MODAL_STYLES.dialog}>
+          <div className="modal-content" style={MODAL_STYLES.content}>
+            <div className="modal-header">
+              <h5 className="modal-title" id="imagePreviewModalLabel">
+                {imagePreviewTitle}
+              </h5>
+              <button type="button" className="btn-close" data-bs-dismiss="modal" aria-label={close} />
+            </div>
+            <div className="modal-body text-center p-0" style={MODAL_STYLES.body}>
+              <img
+                src={displayUrl}
+                alt={fullSizeAlt}
+                className="img-fluid"
+                style={{ maxWidth: "100%", margin: 24 }}
+              />
+              {useResetInfo && (
+                <p className="text-muted small px-3" style={{ marginTop: 12, marginBottom: 12 }}>
+                  <i className="bi bi-info-circle me-1" aria-hidden="true" />
+                  {useResetInfo}
+                </p>
+              )}
+            </div>
+            <div className="modal-footer">
+              <button type="button" className="btn btn-secondary" data-bs-dismiss="modal">
+                {close}
+              </button>
+            </div>
+          </div>
+        </div>
+      </div>
+    );
+  }
+
+  renderUploadModal() {
+    const { uploadPending, uploadError, uploadComplete, isDragOver, wrongFileTypeWarning } = this.state;
+    const {
+      uploadImageTitle,
+      close,
+      uploadSuccess,
+      uploading,
+      dragDropHint,
+      pasteHint,
+      dropZoneAriaLabel
+    } = this.props;
+
+    const isDisabled = uploadPending || uploadComplete;
+
+    return (
+      <div
+        className="modal fade"
+        ref={this.uploadModalRef}
+        tabIndex={-1}
+        aria-labelledby="uploadImageModalLabel"
+        aria-hidden="true"
+      >
+        <div className="modal-dialog modal-dialog-centered" style={MODAL_STYLES.dialog}>
+          <div className="modal-content">
+            <div className="modal-header">
+              <h5 className="modal-title" id="uploadImageModalLabel">
+                {uploadImageTitle}
+              </h5>
+              <button disabled={uploadPending} type="button" className="btn-close" data-bs-dismiss="modal" aria-label={close} />
+            </div>
+            <div className="modal-body" style={MODAL_STYLES.body}>
+              <input
+                ref={this.fileInputRef}
+                type="file"
+                accept="image/*"
+                className="d-none"
+                onChange={this.handleFileChange}
+                disabled={isDisabled}
+                aria-hidden="true"
+              />
+              {uploadComplete && (
+                <div className="alert alert-success mb-3" role="status">
+                  <i className="bi bi-check-circle me-2" aria-hidden="true" />
+                  {uploadSuccess}
+                </div>
+              )}
+              {wrongFileTypeWarning && (
+                <div className="alert alert-warning mb-3" role="alert">
+                  <i className="bi bi-exclamation-triangle me-2" aria-hidden="true" />
+                  {wrongFileTypeWarning}
+                </div>
+              )}
+              {uploadError && (
+                <div className="alert alert-danger mb-3" role="alert">
+                  {uploadError}
+                </div>
+              )}
+              <DropZone
+                isDisabled={isDisabled}
+                isDragOver={isDragOver}
+                onSelect={this.showFilePicker}
+                onDragOver={this.handleDragOver}
+                onDragLeave={this.handleDragLeave}
+                onDrop={this.handleDrop}
+                dragDropHint={dragDropHint}
+                pasteHint={pasteHint}
+                ariaLabel={dropZoneAriaLabel}
+                uploading={uploading}
+                uploadPending={uploadPending}
+              />
+              <button
+                type="button"
+                className="btn btn-primary"
+                data-bs-dismiss="modal"
+                disabled={uploadPending}
+              >
+                {close}
+              </button>
+            </div>
+          </div>
+        </div>
+      </div>
+    );
+  }
+
+  render() {
+    const { imageUrl, addImage, previewAlt, viewFullSize } = this.props;
+    const displayUrl = this.state.currentUrl || imageUrl;
+
+    return (
+      <>
+        {!displayUrl ? (
+          <span
+            className="text-primary"
+            style={{ cursor: "pointer", textDecoration: "underline" }}
+            onClick={this.showUploadModal}
+            onKeyDown={(e) => e.key === "Enter" && this.showUploadModal()}
+            role="button"
+            tabIndex={0}
+            aria-label={addImage}
+          >
+            {addImage}
+          </span>
+        ) : (
+          <img
+            src={displayUrl}
+            alt={previewAlt}
+            className="img-thumbnail"
+            style={{ maxHeight: "60px", width: "auto", cursor: "pointer" }}
+            onClick={this.showPreviewModal}
+            onKeyDown={(e) => e.key === "Enter" && this.showPreviewModal()}
+            role="button"
+            tabIndex={0}
+            aria-label={viewFullSize}
+          />
+        )}
+        {this.renderPreviewModal()}
+        {this.renderUploadModal()}
+      </>
+    );
+  }
+}
+
+const I18N_DEFAULTS = {
+  addImage: "Add image",
+  imagePreviewTitle: "Image Preview",
+  uploadImageTitle: "Upload Image",
+  close: "Close",
+  uploadSuccess: "Image uploaded successfully.",
+  uploading: "Uploading…",
+  dragDropHint: "Drag & drop image here",
+  pasteHint: "or paste with Ctrl+V",
+  dropZoneAriaLabel: "Drop image here or paste with Ctrl+V",
+  wrongFileType: "Please select an image file (e.g. PNG, JPEG, GIF).",
+  fullSizeAlt: "Full size preview",
+  previewAlt: "Preview",
+  viewFullSize: "Click to view full size"
+};
+
+ImageUpload.propTypes = {
+  imageUrl: PropTypes.string,
+  uploadUrl: PropTypes.string.isRequired,
+  formId: PropTypes.string,
+  fieldName: PropTypes.string,
+  fileFieldName: PropTypes.string,
+  useResetInfo: PropTypes.string,
+  addImage: PropTypes.string,
+  imagePreviewTitle: PropTypes.string,
+  uploadImageTitle: PropTypes.string,
+  close: PropTypes.string,
+  uploadSuccess: PropTypes.string,
+  uploading: PropTypes.string,
+  dragDropHint: PropTypes.string,
+  pasteHint: PropTypes.string,
+  dropZoneAriaLabel: PropTypes.string,
+  wrongFileType: PropTypes.string,
+  fullSizeAlt: PropTypes.string,
+  previewAlt: PropTypes.string,
+  viewFullSize: PropTypes.string
+};
+
+ImageUpload.defaultProps = I18N_DEFAULTS;
+
+export default ImageUpload;
diff --git a/app/javascript/components/admin/Initializer.jsx b/app/javascript/components/admin/Initializer.jsx
index 2320644..5ab1b99 100644
--- a/app/javascript/components/admin/Initializer.jsx
+++ b/app/javascript/components/admin/Initializer.jsx
@@ -1,5 +1,6 @@
 import $ from 'jquery';
 import CurriculumEditor from './curriculum/CurriculumEditor';
+import ImageUpload from './ImageUpload';
 import ImportStatus from './ImportStatus';
 import MultiSelectedOperation from './MultiSelectedOperation';
 import React from 'react';
@@ -9,6 +10,7 @@ class Initializer {
   static initialize() {
     // Mount internal components
     Initializer.#initializeCurriculumEditor();
+    Initializer.#initializeImageUpload();
     Initializer.#InitializeImportStatus();
     Initializer.#initializeMultiSelectedOperation();
 
@@ -25,6 +27,14 @@ class Initializer {
     });
   }
 
+  static #initializeImageUpload() {
+    document.querySelectorAll('[id="#lcms-engine-ImageUpload"]').forEach(e => {
+      const props = JSON.parse(e.dataset.content);
+      e.removeAttribute('data-content');
+      ReactDOM.render(<ImageUpload {...props} />, e);
+    });
+  }
+
   static #InitializeImportStatus() {
     document.querySelectorAll('[id="#lcms-engine-ImportStatus"]').forEach(e => {
       const props = JSON.parse(e.dataset.content);
@@ -61,6 +71,7 @@ class Initializer {
       $('.table input[type=checkbox][name="selected_ids[]"]').prop('checked', checked);
     });
   }
+
 }
 
 export default Initializer;
diff --git a/app/models/setting.rb b/app/models/setting.rb
new file mode 100644
index 0000000..413bc39
--- /dev/null
+++ b/app/models/setting.rb
@@ -0,0 +1,72 @@
+class Setting < ApplicationRecord
+  CACHE_PREFIX = "settings"
+
+  validates :key, presence: true
+  validates :value, presence: true
+
+  after_commit :expire_cache
+
+  class << self
+    def cache_key_for(key, include_defaults: false)
+      "#{CACHE_PREFIX}/#{key}#{"_with_defaults" if include_defaults}"
+    end
+
+    def get(key, include_defaults: false)
+      result = find_by(key: key)
+      db_settings = result&.value
+
+      if include_defaults
+        db_settings = merge_with_defaults(key, db_settings)
+      end
+
+      db_settings
+    end
+
+    def merge_with_defaults(key, settings)
+      symbolized = (settings || {})
+        .reject { |_k, v| v.blank? }
+        .transform_keys(&:to_sym)
+
+      SETTINGS_DEFAULTS[key.to_sym]&.merge(symbolized) || symbolized
+    end
+
+    def get_multiple(keys, include_defaults: false)
+      settings_rows = where(key: keys)
+      db_settings = settings_rows.each_with_object({}) do |row, hash|
+        hash[row.key.to_sym] = row.value
+      end
+
+      return db_settings unless include_defaults
+
+      keys.each do |key|
+        db_settings[key.to_sym] = merge_with_defaults(key, db_settings[key.to_sym])
+      end
+
+      db_settings
+    end
+
+    def set(key, value)
+      record = find_or_initialize_by(key: key)
+      record.update!(value: value)
+    end
+
+    def unset(key)
+      find_by(key: key)&.destroy
+    end
+
+    def unset_within(key, sub_key)
+      settings = get(key)
+      return unless settings
+
+      settings.delete(sub_key.to_s)
+      settings.blank? ? unset(key) : set(key, settings)
+    end
+  end
+
+  private
+
+  def expire_cache
+    Rails.cache.delete(self.class.cache_key_for(key))
+    Rails.cache.delete(self.class.cache_key_for(key, include_defaults: true))
+  end
+end
diff --git a/app/services/s3_service.rb b/app/services/s3_service.rb
index 406aa75..632e618 100644
--- a/app/services/s3_service.rb
+++ b/app/services/s3_service.rb
@@ -105,4 +105,14 @@ def upload_local(key, data)
   def self.url_for(key)
     create_object(key).public_url
   end
+
+  # Deletes an object from S3. No-op when AWS_S3_BLOCK is true.
+  #
+  # @param key [String] The S3 object key (e.g. "uploads/settings/logo.png")
+  #
+  def self.delete_object(key)
+    return if AWS_S3_BLOCK
+
+    create_object(key).delete
+  end
 end
diff --git a/app/uploaders/image_uploader.rb b/app/uploaders/image_uploader.rb
new file mode 100644
index 0000000..a323018
--- /dev/null
+++ b/app/uploaders/image_uploader.rb
@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+class ImageUploader < CarrierWave::Uploader::Base
+  MIME_TO_EXTENSION = {
+    "image/png" => ".png",
+    "image/jpeg" => ".jpg",
+    "image/jpg" => ".jpg",
+    "image/gif" => ".gif",
+    "image/webp" => ".webp",
+    "image/svg+xml" => ".svg"
+  }.freeze
+
+  def store_dir
+    "uploads/settings"
+  end
+
+  def filename
+    ext = original_filename.present? ? File.extname(original_filename) : extension_fallback
+    @filename_cache ||= "#{SecureRandom.hex(8)}#{ext}"
+  end
+
+  def extension_allowlist
+    %w(jpg jpeg png gif webp svg)
+  end
+
+  private
+
+  def extension_fallback
+    return ".#{file.extension}" if file.present? && file.respond_to?(:extension) && file.extension.present?
+    return extension_from_mime_type if file.present? && file.respond_to?(:content_type) && file.content_type.present?
+
+    raise CarrierWave::IntegrityError, "Unable to determine file type"
+  end
+
+  def extension_from_mime_type
+    ext = MIME_TO_EXTENSION[file.content_type]
+    raise CarrierWave::IntegrityError, "Unsupported file type: #{file.content_type}" if ext.blank?
+
+    ext
+  end
+end
diff --git a/app/views/admin/settings/edit.html.erb b/app/views/admin/settings/edit.html.erb
new file mode 100644
index 0000000..cf439d1
--- /dev/null
+++ b/app/views/admin/settings/edit.html.erb
@@ -0,0 +1,15 @@
+
+<div class="container-fluid">
+  <h1 class="text-center p-4"><%= t("admin.nav.settings") %></h1>
+  <hr>
+  <div class="row">
+    <div class="col-sm-6">
+      <%= render partial: "admin/settings/edit/#{@setting_type.to_s.underscore}",
+        locals: {
+          setting_group: @setting_group,
+          setting_key: @setting_key,
+          setting_value: @setting_value
+        } %>
+    </div>
+  </div>
+</div>
diff --git a/app/views/admin/settings/edit/_color.html.erb b/app/views/admin/settings/edit/_color.html.erb
new file mode 100644
index 0000000..64da0f5
--- /dev/null
+++ b/app/views/admin/settings/edit/_color.html.erb
@@ -0,0 +1,7 @@
+<form action="<%= admin_settings_path %>" method="put">
+  <div class="form-group">
+    <label for="<%= setting_key %>"><%= t("admin.settings.labels.#{setting_group}.#{setting_key}") %></label>
+    <input type="color" name="<%= setting_key %>" id="<%= setting_key %>" value="<%= setting_value %>">
+  </div>
+  <button type="submit" class="btn btn-primary"><%= t("admin.settings.edit.save") %></button>
+</form>
diff --git a/app/views/admin/settings/edit/_image.html.erb b/app/views/admin/settings/edit/_image.html.erb
new file mode 100644
index 0000000..c62a1b2
--- /dev/null
+++ b/app/views/admin/settings/edit/_image.html.erb
@@ -0,0 +1,7 @@
+<form action="<%= admin_settings_path %>" method="put">
+  <div class="form-group">
+    <label for="<%= setting_key %>"><%= t("admin.settings.labels.#{setting_group}.#{setting_key}") %></label>
+    <input type="text" name="<%= setting_key %>" id="<%= setting_key %>" value="<%= setting_value %>">
+  </div>
+  <button type="submit" class="btn btn-primary"><%= t("admin.settings.edit.save") %></button>
+</form>
diff --git a/app/views/admin/settings/index.html.erb b/app/views/admin/settings/index.html.erb
new file mode 100644
index 0000000..1c09b37
--- /dev/null
+++ b/app/views/admin/settings/index.html.erb
@@ -0,0 +1,74 @@
+<style>
+  #settings-save-button.disabled {
+    opacity: 0.2;
+    cursor: not-allowed !important;
+    pointer-events: none !important;
+  }
+</style>
+<div class="container-fluid">
+  <h1 class="text-center p-4"><%= t("admin.nav.settings") %></h1>
+  <hr>
+  <div class="row">
+    <div class="col">
+      <% SETTINGS.each do |group, types| %>
+        <h3 class="mt-4"><%= t("admin.settings.groups.#{group}") %></h3>
+        <p><%= t("admin.settings.descriptions.#{group}") %></p>
+        <table class="table table-striped table-bordered">
+          <tr>
+            <th><%= t("admin.settings.index.key") %></th>
+            <th><%= t("admin.settings.index.value") %></th>
+            <th><%= t("admin.settings.index.actions") %></th>
+          </tr>
+          <% types.each_key do |key| %>
+            <% value = @all_settings[group][key] %>
+            <tr height="40px">
+              <td height="40px" valign="middle"><%= t("admin.settings.labels.#{group}.#{key}") %></td>
+              <td height="40px" valign="middle">
+                <% if types[key].present? %>
+                  <%= render partial: "admin/settings/show/#{types[key].to_s.underscore}", locals: { setting_key: key, setting_value: value, form_id: "settings-form" } %>
+                <% else %>
+                  <%= value %>
+                <% end %>
+              </td>
+              <td width="250px" height="40px" class="text-end" valign="middle">
+                <%= form_tag entry_admin_settings_path(key: key), method: :delete, data: { turbo: false }, class: "d-inline" do %>
+                  <button type="submit" class="btn btn-warning" data-confirm="<%= j t('admin.settings.index.reset_confirm') %>" onclick="return confirm(this.dataset.confirm)">
+                    <i class="bi bi-arrow-clockwise"></i>
+                    <%= t("admin.settings.index.reset") %>
+                  </button>
+                <% end %>
+              </td>
+            </tr>
+          <% end %>
+        </table>
+      <% end %>
+
+      <%= form_with url: admin_settings_path, method: :patch, id: "settings-form", data: { turbo: false } do |f| %>
+        <button
+          type="submit"
+          class="btn btn-primary disabled"
+          id="settings-save-button"
+        >
+          <i class="bi bi-floppy-fill"></i>
+          <%= t("admin.settings.edit.save") %>
+        </button>
+      <% end %>
+    </div>
+  </div>
+</div>
+<script type="text/javascript">
+  (function() {
+    function handleChange(e) {
+      const btn = document.getElementById("settings-save-button");
+      if (btn) {
+        btn.disabled = false;
+        btn.classList.remove("disabled");
+      }
+    }
+
+    document.querySelectorAll("input[form='settings-form']")
+      .forEach(input => input.addEventListener("change", handleChange));
+
+    document.querySelector('#settings-form').addEventListener("change", handleChange);
+  })();
+</script>
diff --git a/app/views/admin/settings/show/_color.html.erb b/app/views/admin/settings/show/_color.html.erb
new file mode 100644
index 0000000..8bf327e
--- /dev/null
+++ b/app/views/admin/settings/show/_color.html.erb
@@ -0,0 +1,7 @@
+<input
+  type="color"
+  name="<%= setting_key %>"
+  form="<%= form_id %>"
+  value="<%= setting_value %>"
+  onchange="document.documentElement.style.setProperty('--<%= setting_key %>', this.value);"
+>
diff --git a/app/views/admin/settings/show/_image.html.erb b/app/views/admin/settings/show/_image.html.erb
new file mode 100644
index 0000000..32d0872
--- /dev/null
+++ b/app/views/admin/settings/show/_image.html.erb
@@ -0,0 +1,23 @@
+<div class="settings-image-field">
+  <input type="hidden" name="<%= setting_key %>" form="<%= form_id %>" value="<%= setting_value %>">
+  <%= render_component "ImageUpload", {
+    imageUrl: setting_value,
+    fieldName: setting_key,
+    uploadUrl: upload_image_admin_settings_path,
+    formId: form_id,
+    useResetInfo: t("admin.settings.image_preview.use_reset"),
+    addImage: t("admin.settings.image_upload.add_image"),
+    imagePreviewTitle: t("admin.settings.image_upload.image_preview_title"),
+    uploadImageTitle: t("admin.settings.image_upload.upload_image_title"),
+    close: t("admin.settings.image_upload.close"),
+    uploadSuccess: t("admin.settings.image_upload.upload_success"),
+    uploading: t("admin.settings.image_upload.uploading"),
+    dragDropHint: t("admin.settings.image_upload.drag_drop_hint"),
+    pasteHint: t("admin.settings.image_upload.paste_hint", shortcut: t("admin.settings.image_upload.paste_shortcut")),
+    dropZoneAriaLabel: t("admin.settings.image_upload.drop_zone_aria_label"),
+    wrongFileType: t("admin.settings.image_upload.wrong_file_type"),
+    fullSizeAlt: t("admin.settings.image_upload.full_size_alt"),
+    previewAlt: t("admin.settings.image_upload.preview_alt"),
+    viewFullSize: t("admin.settings.image_upload.view_full_size")
+  } %>
+</div>
diff --git a/app/views/shared/_header.html.erb b/app/views/shared/_header.html.erb
index c8ecde2..dd9102f 100644
--- a/app/views/shared/_header.html.erb
+++ b/app/views/shared/_header.html.erb
@@ -1,6 +1,34 @@
-<nav class="navbar navbar-expand-lg bg-light sticky-top">
+<style>
+  :root {
+    --header_bg_color: <%= @header_settings[:header_bg_color] %>;
+    --header_text_color: <%= @header_settings[:header_text_color] %>;
+    --header_dropdown_bg_color: <%= @header_settings[:header_dropdown_bg_color] %>;
+    --header_active_item_color: <%= @header_settings[:header_active_item_color] %>;
+  }
+
+  .navbar {
+    background-color: var(--header_bg_color) !important;
+    color: var(--header_text_color) !important;
+  }
+
+  .nav-link { color: var(--header_text_color) !important; }
+  .navbar .dropdown-menu { background-color: var(--header_dropdown_bg_color); }
+  .navbar .dropdown-item:hover,
+  .navbar .dropdown-item:focus { background-color: var(--header_active_item_color); }
+</style>
+
+<nav
+  class="navbar navbar-expand-lg sticky-top"
+  style="background-color: <%= @header_settings[:header_bg_color] %>; color: <%= @header_settings[:header_text_color] %>;"
+>
   <div class="container-fluid">
-    <%= link_to 'LCMS', root_path, class: 'navbar-brand' %>
+    <%= link_to root_path, class: 'navbar-brand' do %>
+      <% if @header_settings[:header_logo].present? %>
+        <%= image_tag @header_settings[:header_logo], class: 'navbar-brand-logo', style: 'max-height: 40px;' %>
+      <% else %>
+        <%= 'LCMS' %>
+      <% end %>
+    <% end %>
     <button class="navbar-toggler" type="button" data-bs-toggle="collapse" data-bs-target="#navbarSupportedContent" aria-controls="navbarSupportedContent" aria-expanded="false" aria-label="Toggle navigation">
       <span class="navbar-toggler-icon"></span>
     </button>
@@ -36,6 +64,9 @@
               <%= render_plugin_items_for(:users) %>
             </ul>
           </li>
+          <li class="nav-item">
+            <%= link_to t('admin.nav.settings'), admin_settings_path, class: 'nav-link' %>
+          </li>
           <%= render_plugin_menu_items %>
         </ul>
         <ul class="navbar-nav ms-auto">
diff --git a/config/initializers/lcms_constants.rb b/config/initializers/lcms_constants.rb
index 000a417..5c28184 100644
--- a/config/initializers/lcms_constants.rb
+++ b/config/initializers/lcms_constants.rb
@@ -32,3 +32,23 @@
   math: "MATH"
 }.with_indifferent_access.freeze
 SUBJECT_DEFAULT = "math"
+
+SETTINGS = {
+  appearance: {
+    header_bg_color: :color,
+    header_text_color: :color,
+    header_dropdown_bg_color: :color,
+    header_active_item_color: :color,
+    header_logo: :image
+  }
+}.freeze
+
+SETTINGS_DEFAULTS = {
+  appearance: {
+    header_bg_color: "#f8f9fa",
+    header_text_color: "#000000",
+    header_dropdown_bg_color: "#ffffff",
+    header_active_item_color: "#0d6efd",
+    header_logo: nil
+  }
+}.freeze
diff --git a/config/locales/admin/en.yml b/config/locales/admin/en.yml
index 06a787b..8c9cb6e 100644
--- a/config/locales/admin/en.yml
+++ b/config/locales/admin/en.yml
@@ -102,10 +102,6 @@ en:
         page_title: New Page
       update:
         success: Page updated successfully.
-    settings:
-      toggle_editing_enabled:
-        disabled: Resource editing disabled.
-        enabled: Resource editing enabled.
     staff_members:
       create:
         success: Staff Member created successfully.
@@ -244,6 +240,7 @@ en:
       update:
         success: Standard updated
     nav:
+      settings: Settings
       curriculum: Curriculum
       resources: Resources
       users: Users
@@ -264,3 +261,49 @@ en:
         success: Unit deleted successfully.
       destroy_selected:
         success: '%{count} units have been deleted successfully.'
+    settings:
+      toggle_editing_enabled:
+        disabled: Resource editing disabled.
+        enabled: Resource editing enabled.
+      invalid_group: Invalid settings group.
+      groups:
+        appearance: Appearance
+      descriptions:
+        appearance: Customize the appearance of the admin panel interface.
+      labels:
+        appearance:
+          header_bg_color: Header Background Color
+          header_text_color: Header Text Color
+          header_dropdown_bg_color: Header Dropdown Background Color
+          header_active_item_color: Header Active Item Color
+          header_logo: Header Logo
+      index:
+        key: Key
+        value: Value
+        actions: Actions
+        reset: Reset
+        reset_confirm: Are you sure you want to delete this setting? To undo unsaved changes, please refresh the page.
+      edit:
+        page_title: Edit Setting
+        save: Save changes
+      updated:
+        success: Setting updated successfully.
+      deleted:
+        success: Setting deleted successfully.
+      image_preview:
+        use_reset: To change the image, please use the Reset button in the settings screen.
+      image_upload:
+        add_image: Add image
+        image_preview_title: Image Preview
+        upload_image_title: Upload Image
+        close: Close
+        upload_success: Image uploaded successfully. Please remember to save the changes.
+        uploading: Uploading…
+        drag_drop_hint: Drag & drop image here
+        paste_hint: "or paste with %{shortcut} or click to select local file"
+        paste_shortcut: Ctrl+V
+        drop_zone_aria_label: Drop image here or paste with Ctrl+V (click to select local file)
+        wrong_file_type: Please select an image file (e.g. PNG, JPEG, GIF).
+        full_size_alt: Full size preview
+        preview_alt: Preview
+        view_full_size: Click to view full size
diff --git a/config/routes.rb b/config/routes.rb
index dc8e2c8..322ebb9 100644
--- a/config/routes.rb
+++ b/config/routes.rb
@@ -38,6 +38,12 @@
       post :reset_password, on: :member
     end
 
+    resource :settings, only: [:update] do
+      get :index, path: ""
+      delete ":key", action: :destroy, as: :entry
+      post :upload_image
+    end
+
     resources :standards, only: %i(index edit update) do
       post :import, on: :collection
     end
diff --git a/db/migrate/20260219081358_create_settings.rb b/db/migrate/20260219081358_create_settings.rb
new file mode 100644
index 0000000..a9e9394
--- /dev/null
+++ b/db/migrate/20260219081358_create_settings.rb
@@ -0,0 +1,11 @@
+class CreateSettings < ActiveRecord::Migration[8.1]
+  def change
+    create_table :settings do |t|
+      t.string :key, null: false
+      t.jsonb :value
+
+      t.timestamps
+    end
+    add_index :settings, :key, unique: true
+  end
+end
diff --git a/db/schema.rb b/db/schema.rb
index e1b85a3..8e23801 100644
--- a/db/schema.rb
+++ b/db/schema.rb
@@ -10,7 +10,7 @@
 #
 # It's strongly recommended that you check this file into your version control system.
 
-ActiveRecord::Schema[8.1].define(version: 2026_02_12_043346) do
+ActiveRecord::Schema[8.1].define(version: 2026_02_19_081358) do
   # These are extensions that must be enabled in order to support this database
   enable_extension "hstore"
   enable_extension "pg_catalog.plpgsql"
@@ -173,6 +173,14 @@
     t.index ["updated_at"], name: "index_sessions_on_updated_at"
   end
 
+  create_table "settings", force: :cascade do |t|
+    t.datetime "created_at", null: false
+    t.string "key", null: false
+    t.datetime "updated_at", null: false
+    t.jsonb "value"
+    t.index ["key"], name: "index_settings_on_key", unique: true
+  end
+
   create_table "standards", id: :serial, force: :cascade do |t|
     t.text "alt_names", default: [], null: false, array: true
     t.string "course"
diff --git a/spec/factories/settings.rb b/spec/factories/settings.rb
new file mode 100644
index 0000000..661d039
--- /dev/null
+++ b/spec/factories/settings.rb
@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+FactoryBot.define do
+  factory :setting do
+    sequence(:key) { |n| "setting_key_#{n}" }
+    value { "setting_value" }
+  end
+end
diff --git a/spec/models/setting_spec.rb b/spec/models/setting_spec.rb
new file mode 100644
index 0000000..4d059d6
--- /dev/null
+++ b/spec/models/setting_spec.rb
@@ -0,0 +1,156 @@
+# frozen_string_literal: true
+
+require "rails_helper"
+
+RSpec.describe Setting, type: :model do
+  describe "validations" do
+    it { is_expected.to validate_presence_of(:key) }
+    it { is_expected.to validate_presence_of(:value) }
+  end
+
+  describe ".merge_with_defaults" do
+    it "correctly selects the values or their defaults" do
+      key = :appearance
+      settings = { "header_bg_color" => "#ff0000", "header_text_color" => nil }
+
+      result = described_class.merge_with_defaults(key, settings)
+
+      defaults = SETTINGS_DEFAULTS[:appearance]
+
+      expect(result[:header_bg_color]).to eq("#ff0000")
+      expect(result[:header_text_color]).to eq(defaults[:header_text_color])
+      expect(result[:header_dropdown_bg_color]).to eq(defaults[:header_dropdown_bg_color])
+      expect(result[:header_active_item_color]).to eq(defaults[:header_active_item_color])
+      expect(result[:header_logo]).to eq(defaults[:header_logo])
+    end
+
+    it "returns all defaults when given an empty hash" do
+      result = described_class.merge_with_defaults(:appearance, {})
+
+      SETTINGS_DEFAULTS[:appearance].each do |key, default_value|
+        expect(result[key]).to eq(default_value)
+      end
+    end
+
+    it "returns all defaults when given nil" do
+      result = described_class.merge_with_defaults(:appearance, nil)
+
+      SETTINGS_DEFAULTS[:appearance].each do |key, default_value|
+        expect(result[key]).to eq(default_value)
+      end
+    end
+  end
+
+  describe ".get" do
+    it "returns the raw setting value without defaults" do
+      described_class.create!(key: :appearance, value: { "header_bg_color" => "#ff0000" })
+      result = described_class.get(:appearance)
+
+      expect(result).to eq({ "header_bg_color" => "#ff0000" })
+    end
+
+    it "returns the setting value merged with defaults" do
+      described_class.create!(key: :appearance, value: { "header_bg_color" => "#ff0000" })
+      result = described_class.get(:appearance, include_defaults: true)
+
+      expect(result[:header_bg_color]).to eq("#ff0000")
+      expect(result[:header_text_color]).to eq(SETTINGS_DEFAULTS[:appearance][:header_text_color])
+    end
+
+    it "returns all defaults when the setting is not present" do
+      result = described_class.get(:appearance, include_defaults: true)
+
+      SETTINGS_DEFAULTS[:appearance].each do |key, default_value|
+        expect(result[key]).to eq(default_value)
+      end
+    end
+
+    it "returns nil when the setting is not present and defaults are not included" do
+      result = described_class.get(:nonexistent_key)
+      expect(result).to be_nil
+    end
+  end
+
+  describe ".get_multiple" do
+    it "returns an empty hash when no settings exist" do
+      result = described_class.get_multiple(%w(header_bg_color header_text_color))
+      expect(result).to be_empty
+    end
+
+    it "returns stored values" do
+      described_class.create!(key: :appearance, value: { "header_bg_color" => "#ff0000" })
+      described_class.create!(key: :other, value: { "some_key" => "Hello World!" })
+
+      result = described_class.get_multiple(%i(appearance other), include_defaults: false)
+
+      expect(result[:appearance]["header_bg_color"]).to eq("#ff0000")
+      expect(result[:other]["some_key"]).to eq("Hello World!")
+    end
+
+    it "returns stored values with defaults" do
+      described_class.create!(key: :appearance, value: { "header_bg_color" => "#ff0000" })
+      described_class.create!(key: :other, value: { "some_key" => "Hello World!" })
+
+      result = described_class.get_multiple(%i(appearance other), include_defaults: true)
+
+      expect(result[:appearance][:header_bg_color]).to eq("#ff0000")
+      expect(result[:other][:some_key]).to eq("Hello World!")
+
+      SETTINGS_DEFAULTS[:appearance].each do |key, default_value|
+        next if key == :header_bg_color
+
+        expect(result[:appearance][key]).to eq(default_value)
+      end
+    end
+  end
+
+  describe ".set" do
+    it "creates a new setting when it does not exist" do
+      expect {
+        described_class.set(:appearance, { "header_bg_color" => "#ff0000" })
+      }.to change(described_class, :count).by(1)
+
+      expect(described_class.find_by(key: :appearance).value).to eq({ "header_bg_color" => "#ff0000" })
+    end
+
+    it "updates an existing setting" do
+      described_class.create!(key: :appearance, value: { "header_bg_color" => "#ff0000" })
+
+      expect {
+        described_class.set(:appearance, { "header_bg_color" => "#00ff00" })
+      }.not_to change(described_class, :count)
+
+      expect(described_class.find_by(key: :appearance).value).to eq({ "header_bg_color" => "#00ff00" })
+    end
+  end
+
+  describe ".unset" do
+    it "destroys an existing setting" do
+      described_class.create!(key: :appearance, value: { "header_bg_color" => "#ff0000" })
+
+      expect {
+        described_class.unset(:appearance)
+      }.to change(described_class, :count).by(-1)
+
+      expect(described_class.find_by(key: :appearance)).to be_nil
+    end
+
+    it "does nothing when the setting does not exist" do
+      expect {
+        described_class.unset("nonexistent_key")
+      }.not_to change(described_class, :count)
+    end
+  end
+
+  describe ".unset_within" do
+    it "unsets a specific sub key within a key" do
+      described_class.create!(key: :appearance, value: { "header_bg_color" => "#ff0000", "header_text_color" => "#000000" })
+
+      expect {
+        described_class.unset_within(:appearance, :header_bg_color)
+      }.not_to change(described_class, :count)
+
+      expect(described_class.find_by(key: :appearance).value).to eq({ "header_text_color" => "#000000" })
+    end
+  end
+end
diff --git a/spec/requests/admin/settings_spec.rb b/spec/requests/admin/settings_spec.rb
new file mode 100644
index 0000000..df86945
--- /dev/null
+++ b/spec/requests/admin/settings_spec.rb
@@ -0,0 +1,222 @@
+# frozen_string_literal: true
+
+require "rails_helper"
+
+RSpec.describe "Admin::Settings", type: :request do
+  let(:admin) { create(:admin) }
+  let(:settings_path) { "/admin/settings" }
+
+  before { login_as(admin, scope: :user) }
+
+  describe "authentication" do
+    context "when not signed in" do
+      before { logout }
+
+      it "redirects to the sign-in page" do
+        get settings_path
+        expect(response).to redirect_to(new_user_session_path)
+      end
+    end
+
+    context "when signed in as a non-admin user" do
+      let(:user) { create(:user) }
+
+      before do
+        logout
+        login_as(user, scope: :user)
+      end
+
+      it "redirects to root" do
+        get settings_path
+        expect(response).to redirect_to(root_path)
+      end
+    end
+  end
+
+  describe "GET /admin/settings (index)" do
+    it "returns a successful response" do
+      get settings_path
+      expect(response).to have_http_status(:ok)
+    end
+
+    it "displays settings from all groups" do
+      Setting.set(:appearance, { "header_bg_color" => "#ff0000" })
+
+      get settings_path
+
+      expect(response.body).to include("#ff0000")
+    end
+  end
+
+  describe "PATCH /admin/settings (update)" do
+    it "saves settings and redirects with a success notice" do
+      patch settings_path, params: { header_bg_color: "#ff0000" }
+
+      expect(response).to redirect_to(settings_path)
+      follow_redirect!
+      expect(response.body).to include("Setting updated successfully")
+
+      setting = Setting.find_by(key: "appearance")
+      expect(setting.value["header_bg_color"]).to eq("#ff0000")
+    end
+
+    it "updates multiple settings at once" do
+      patch settings_path, params: {
+        header_bg_color: "#ff0000",
+        header_text_color: "#00ff00"
+      }
+
+      expect(response).to redirect_to(settings_path)
+      setting = Setting.find_by(key: "appearance")
+      expect(setting.value["header_bg_color"]).to eq("#ff0000")
+      expect(setting.value["header_text_color"]).to eq("#00ff00")
+    end
+
+    it "does not persist non-permitted params" do
+      patch settings_path, params: { some_random_key: "value" }
+
+      expect(response).to redirect_to(settings_path)
+      expect(Setting.find_by(key: "appearance")).to be_nil
+    end
+
+    context "with image upload" do
+      let(:uploader) { instance_double(ImageUploader, store!: true, url: "/uploads/settings/image.png") }
+      let(:image_file) do
+        Tempfile.new(["test_image", ".png"]).tap do |f|
+          f.binmode
+          f.write("\x89PNG\r\n\x1a\n")
+          f.rewind
+        end
+      end
+      let(:uploaded_file) { Rack::Test::UploadedFile.new(image_file.path, "image/png") }
+
+      before do
+        allow(ImageUploader).to receive(:new).and_return(uploader)
+      end
+
+      after { image_file.close! }
+
+      it "processes the image upload and stores its URL as a setting" do
+        patch settings_path, params: { header_logo: uploaded_file }
+
+        expect(response).to redirect_to(settings_path)
+        expect(uploader).to have_received(:store!)
+        setting = Setting.find_by(key: "appearance")
+        expect(setting.value["header_logo"]).to eq("/uploads/settings/image.png")
+      end
+
+      it "deletes the old image before storing a new one" do
+        Setting.set(:appearance, { "header_logo" => "/uploads/settings/old_image.png" })
+        old_path = Rails.root.join("public", "uploads/settings/old_image.png")
+        allow(old_path).to receive(:exist?).and_return(false)
+
+        patch settings_path, params: { header_logo: uploaded_file }
+
+        expect(response).to redirect_to(settings_path)
+        setting = Setting.find_by(key: "appearance")
+        expect(setting.value["header_logo"]).to eq("/uploads/settings/image.png")
+      end
+    end
+  end
+
+  describe "DELETE /admin/settings/:key (destroy)" do
+    it "resets a setting and redirects" do
+      Setting.set(:appearance, { "header_bg_color" => "#ff0000", "header_text_color" => "#000000" })
+
+      delete "#{settings_path}/header_bg_color"
+
+      expect(response).to redirect_to(settings_path)
+      follow_redirect!
+      expect(response.body).to include("Setting deleted successfully")
+
+      setting = Setting.find_by(key: "appearance")
+      expect(setting.value).not_to have_key("header_bg_color")
+      expect(setting.value["header_text_color"]).to eq("#000000")
+    end
+
+    it "handles deletion when no settings exist gracefully" do
+      delete "#{settings_path}/header_bg_color"
+      expect(response).to redirect_to(settings_path)
+    end
+
+    context "when deleting an image setting with a local file" do
+      before do
+        Setting.set(:appearance, { "header_logo" => "/uploads/settings/image.png", "header_bg_color" => "#ffffff" })
+      end
+
+      it "removes the setting value" do
+        delete "#{settings_path}/header_logo"
+
+        setting = Setting.find_by(key: "appearance")
+        expect(setting.value).not_to have_key("header_logo")
+      end
+
+      it "deletes the local file" do
+        local_path = Rails.root.join("public", "uploads/settings/image.png")
+        FileUtils.mkdir_p(local_path.dirname)
+        FileUtils.touch(local_path)
+
+        delete "#{settings_path}/header_logo"
+
+        expect(File.exist?(local_path)).to be false
+      end
+    end
+
+    context "when deleting an image setting with an S3 URL" do
+      before do
+        Setting.set(:appearance, { "header_logo" => "https://bucket.s3.amazonaws.com/uploads/settings/image.png", "header_bg_color" => "#ffffff" })
+        allow(S3Service).to receive(:delete_object)
+      end
+
+      it "removes the setting and calls S3Service.delete_object" do
+        delete "#{settings_path}/header_logo"
+
+        expect(S3Service).to have_received(:delete_object).with("uploads/settings/image.png")
+        setting = Setting.find_by(key: "appearance")
+        expect(setting.value).not_to have_key("header_logo")
+      end
+    end
+  end
+
+  describe "POST /admin/settings/upload_image" do
+    let(:uploader) { instance_double(ImageUploader, store!: true, url: "/uploads/settings/image.png") }
+    let(:image_file) do
+      Tempfile.new(["test_image", ".png"]).tap do |f|
+        f.binmode
+        f.write("\x89PNG\r\n\x1a\n")
+        f.rewind
+      end
+    end
+    let(:uploaded_file) { Rack::Test::UploadedFile.new(image_file.path, "image/png") }
+
+    before do
+      allow(ImageUploader).to receive(:new).and_return(uploader)
+    end
+
+    after { image_file.close! }
+
+    it "uploads the image and returns JSON with URL" do
+      post "#{settings_path}/upload_image", params: { image: uploaded_file }
+
+      expect(response).to have_http_status(:ok)
+      json = JSON.parse(response.body)
+      expect(json["url"]).to eq("/uploads/settings/image.png")
+    end
+
+    it "returns 422 when no file is provided" do
+      post "#{settings_path}/upload_image", params: { image: "not_a_file" }
+
+      expect(response).to have_http_status(:unprocessable_entity)
+    end
+
+    it "returns 422 when CarrierWave raises an IntegrityError" do
+      allow(uploader).to receive(:store!).and_raise(CarrierWave::IntegrityError, "Invalid file type")
+
+      post "#{settings_path}/upload_image", params: { image: uploaded_file }
+
+      expect(response).to have_http_status(:unprocessable_entity)
+      json = JSON.parse(response.body)
+      expect(json["error"]).to include("Invalid file type")
+    end
+  end
+end

From 0bf671f31c75995c0d5ce4b13d3070335bac5fb3 Mon Sep 17 00:00:00 2001
From: Alexander Kuznetsov <paranoic.san@gmail.com>
Date: Fri, 20 Feb 2026 15:33:32 +0700
Subject: [PATCH 2/2] Update setting storage logic

### Harden Setting model value column

- Add null: false and default: {} to settings.value in migration
- Remove presence validation for value from model (blank? rejects {})
- Guard Setting.set against nil to prevent NOT NULL violations
- Add specs for nil and empty hash handling in Setting.set

### Move image deletion logic from SettingsController to ImageUploader

- Extract delete_by_url class method to ImageUploader with support for local and S3 files
- Remove duplicate deletion methods from SettingsController
- Add specs for ImageUploader.delete_by_url

Signed-off-by: Alexander Kuznetsov <paranoic.san@gmail.com>
---
 app/controllers/admin/settings_controller.rb | 40 +---------
 app/models/setting.rb                        |  3 +-
 app/uploaders/image_uploader.rb              | 37 +++++++++
 db/migrate/20260219081358_create_settings.rb |  2 +-
 db/schema.rb                                 |  2 +-
 spec/models/setting_spec.rb                  | 21 +++++-
 spec/uploaders/image_uploader_spec.rb        | 79 ++++++++++++++++++++
 7 files changed, 144 insertions(+), 40 deletions(-)
 create mode 100644 spec/uploaders/image_uploader_spec.rb

diff --git a/app/controllers/admin/settings_controller.rb b/app/controllers/admin/settings_controller.rb
index 3e8bf47..101b969 100644
--- a/app/controllers/admin/settings_controller.rb
+++ b/app/controllers/admin/settings_controller.rb
@@ -25,7 +25,10 @@ def destroy
       group = group_for_key(key)
       return redirect_to admin_settings_path unless group
 
-      delete_old_image_if_present(group, key) if image_setting?(group, key)
+      if image_setting?(group, key)
+        old_url = Setting.get(group, include_defaults: true)&.dig(key.to_sym)
+        ImageUploader.delete_by_url(old_url)
+      end
       Setting.unset_within(group, key)
       redirect_to admin_settings_path, notice: t("admin.settings.deleted.success"), status: :see_other
     end
@@ -68,40 +71,5 @@ def process_image_uploads(params)
     def image_setting?(group, key)
       key.present? && SETTINGS.dig(group, key.to_sym) == :image
     end
-
-    def delete_old_image_if_present(group, setting_key)
-      settings = Setting.get(group, include_defaults: true)
-      old_url = settings[setting_key.to_sym]
-      return if old_url.blank?
-
-      if stored_locally?(old_url)
-        delete_local_image(old_url)
-      elsif stored_on_s3?(old_url)
-        delete_s3_image(old_url)
-      end
-    rescue StandardError => e
-      Rails.logger.warn "Failed to delete old image: #{e.message}"
-    end
-
-    def stored_locally?(url)
-      url.to_s.start_with?("/uploads/settings/")
-    end
-
-    def stored_on_s3?(url)
-      url.to_s.include?("s3") || url.to_s.include?("amazonaws")
-    end
-
-    def delete_local_image(url)
-      path = Rails.root.join("public", url.to_s.delete_prefix("/"))
-      FileUtils.rm_f(path) if path.exist?
-    end
-
-    def delete_s3_image(url)
-      uri = URI.parse(url)
-      key = URI.decode_www_form_component(uri.path.delete_prefix("/"))
-      return unless key.start_with?("uploads/settings/")
-
-      S3Service.delete_object(key)
-    end
   end
 end
diff --git a/app/models/setting.rb b/app/models/setting.rb
index 413bc39..76bc9e2 100644
--- a/app/models/setting.rb
+++ b/app/models/setting.rb
@@ -2,7 +2,6 @@ class Setting < ApplicationRecord
   CACHE_PREFIX = "settings"
 
   validates :key, presence: true
-  validates :value, presence: true
 
   after_commit :expire_cache
 
@@ -46,6 +45,8 @@ def get_multiple(keys, include_defaults: false)
     end
 
     def set(key, value)
+      return if value.nil?
+
       record = find_or_initialize_by(key: key)
       record.update!(value: value)
     end
diff --git a/app/uploaders/image_uploader.rb b/app/uploaders/image_uploader.rb
index a323018..ad764ab 100644
--- a/app/uploaders/image_uploader.rb
+++ b/app/uploaders/image_uploader.rb
@@ -23,6 +23,43 @@ def extension_allowlist
     %w(jpg jpeg png gif webp svg)
   end
 
+  # Deletes a previously uploaded image by its URL.
+  # Supports both local files and S3-hosted images.
+  def self.delete_by_url(url)
+    return if url.blank?
+
+    if local_url?(url)
+      delete_local(url)
+    elsif s3_url?(url)
+      delete_from_s3(url)
+    end
+  rescue StandardError => e
+    Rails.logger.warn "Failed to delete old image: #{e.message}"
+  end
+
+  def self.local_url?(url)
+    url.to_s.start_with?("/uploads/settings/")
+  end
+
+  def self.s3_url?(url)
+    url.to_s.include?("s3") || url.to_s.include?("amazonaws")
+  end
+
+  def self.delete_local(url)
+    path = Rails.root.join("public", url.to_s.delete_prefix("/"))
+    FileUtils.rm_f(path) if path.exist?
+  end
+
+  def self.delete_from_s3(url)
+    uri = URI.parse(url)
+    key = URI.decode_www_form_component(uri.path.delete_prefix("/"))
+    return unless key.start_with?("uploads/settings/")
+
+    S3Service.delete_object(key)
+  end
+
+  private_class_method :local_url?, :s3_url?, :delete_local, :delete_from_s3
+
   private
 
   def extension_fallback
diff --git a/db/migrate/20260219081358_create_settings.rb b/db/migrate/20260219081358_create_settings.rb
index a9e9394..27f5c73 100644
--- a/db/migrate/20260219081358_create_settings.rb
+++ b/db/migrate/20260219081358_create_settings.rb
@@ -2,7 +2,7 @@ class CreateSettings < ActiveRecord::Migration[8.1]
   def change
     create_table :settings do |t|
       t.string :key, null: false
-      t.jsonb :value
+      t.jsonb :value, null: false, default: {}
 
       t.timestamps
     end
diff --git a/db/schema.rb b/db/schema.rb
index 8e23801..3514c17 100644
--- a/db/schema.rb
+++ b/db/schema.rb
@@ -177,7 +177,7 @@
     t.datetime "created_at", null: false
     t.string "key", null: false
     t.datetime "updated_at", null: false
-    t.jsonb "value"
+    t.jsonb "value", default: {}, null: false
     t.index ["key"], name: "index_settings_on_key", unique: true
   end
 
diff --git a/spec/models/setting_spec.rb b/spec/models/setting_spec.rb
index 4d059d6..60f9e28 100644
--- a/spec/models/setting_spec.rb
+++ b/spec/models/setting_spec.rb
@@ -5,7 +5,6 @@
 RSpec.describe Setting, type: :model do
   describe "validations" do
     it { is_expected.to validate_presence_of(:key) }
-    it { is_expected.to validate_presence_of(:value) }
   end
 
   describe ".merge_with_defaults" do
@@ -122,6 +121,26 @@
 
       expect(described_class.find_by(key: :appearance).value).to eq({ "header_bg_color" => "#00ff00" })
     end
+
+    it "does nothing when value is nil" do
+      expect {
+        described_class.set(:appearance, nil)
+      }.not_to change(described_class, :count)
+    end
+
+    it "does not overwrite existing setting when value is nil" do
+      described_class.create!(key: :appearance, value: { "header_bg_color" => "#ff0000" })
+
+      described_class.set(:appearance, nil)
+
+      expect(described_class.find_by(key: :appearance).value).to eq({ "header_bg_color" => "#ff0000" })
+    end
+
+    it "saves an empty hash" do
+      described_class.set(:appearance, {})
+
+      expect(described_class.find_by(key: :appearance).value).to eq({})
+    end
   end
 
   describe ".unset" do
diff --git a/spec/uploaders/image_uploader_spec.rb b/spec/uploaders/image_uploader_spec.rb
new file mode 100644
index 0000000..96bc42a
--- /dev/null
+++ b/spec/uploaders/image_uploader_spec.rb
@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+
+require "rails_helper"
+
+RSpec.describe ImageUploader do
+  describe ".delete_by_url" do
+    context "when url is blank" do
+      it "does nothing for nil" do
+        expect { described_class.delete_by_url(nil) }.not_to raise_error
+      end
+
+      it "does nothing for empty string" do
+        expect { described_class.delete_by_url("") }.not_to raise_error
+      end
+    end
+
+    context "with a local file" do
+      let(:url) { "/uploads/settings/image.png" }
+      let(:path) { Rails.root.join("public", "uploads/settings/image.png") }
+
+      before do
+        FileUtils.mkdir_p(path.dirname)
+        FileUtils.touch(path)
+      end
+
+      after { FileUtils.rm_f(path) }
+
+      it "deletes the file" do
+        described_class.delete_by_url(url)
+
+        expect(File.exist?(path)).to be false
+      end
+    end
+
+    context "with a local file that does not exist" do
+      it "does not raise" do
+        expect { described_class.delete_by_url("/uploads/settings/nonexistent.png") }.not_to raise_error
+      end
+    end
+
+    context "with an S3 URL" do
+      let(:url) { "https://bucket.s3.amazonaws.com/uploads/settings/image.png" }
+
+      before { allow(S3Service).to receive(:delete_object) }
+
+      it "calls S3Service.delete_object with the correct key" do
+        described_class.delete_by_url(url)
+
+        expect(S3Service).to have_received(:delete_object).with("uploads/settings/image.png")
+      end
+    end
+
+    context "with an S3 URL outside allowed prefix" do
+      let(:url) { "https://bucket.s3.amazonaws.com/other/path/image.png" }
+
+      before { allow(S3Service).to receive(:delete_object) }
+
+      it "does not call S3Service.delete_object" do
+        described_class.delete_by_url(url)
+
+        expect(S3Service).not_to have_received(:delete_object)
+      end
+    end
+
+    context "when an error occurs" do
+      let(:url) { "/uploads/settings/image.png" }
+
+      before do
+        allow(described_class).to receive(:delete_local).and_raise(StandardError, "Something went wrong")
+        allow(Rails.logger).to receive(:warn)
+      end
+
+      it "logs a warning and does not raise" do
+        expect { described_class.delete_by_url(url) }.not_to raise_error
+        expect(Rails.logger).to have_received(:warn).with(/Failed to delete old image/)
+      end
+    end
+  end
+end