Implemented re-branding option for self-hosted users

Author: Lissy93

.github/docs/app-customization.md

@@ -0,0 +1,134 @@
+# Customization Guide
+
+If you're self-hosting Networking Toolbox, you can customize the branding for your instance with a few env vars.
+
+## Overview
+
+Networking Toolbox supports customization through environment variables. This allows you to:
+- Brand the application with your organization's name
+- Use a custom logo/icon
+- Set default themes and layouts
+- Maintain consistency across your organization
+
+**Important:** These customizations only affect the default values. Users can still customize their personal preferences through the settings menu, and those will be stored in their browser's localStorage.
+
+## Getting Started
+
+Download the [`.env.example`](https://gist.githubusercontent.com/Lissy93/3c5f85dc0e2263a4706d3e136f0a076e/raw/62a00f625c920ac9e1cafe60721213e2ea233581/.env.example) to `.env` in the root of your project.
+
+1. Copy `.env.example` to `.env`:
+   ```bash
+    curl -o .env https://gist.githubusercontent.com/Lissy93/3c5f85dc0e2263a4706d3e136f0a076e/raw/62a00f625c920ac9e1cafe60721213e2ea233581/.env.example
+   ```
+
+2. Edit `.env` and uncomment/modify the variables you want to customize
+
+3. Restart your application to apply changes
+
+## Available Customizations
+
+### Site Branding
+
+```bash
+# Customize your site name and description
+NTB_SITE_NAME=My Network Tools
+NTB_SITE_TITLE=My Network Tools
+NTB_SITE_DESCRIPTION=Professional networking utilities for your team
+```
+
+### Custom Logo
+
+Use a custom logo image in the navbar:
+
+```bash
+NTB_SITE_ICON=/logo.svg
+```
+
+Place your logo image in the `static/` directory and reference it with a leading slash. Supported formats: SVG, PNG, JPG, WebP.
+
+### Default Layout
+
+Set the default homepage layout:
+
+```bash
+# Options: categories, default, minimal, carousel, bookmarks, small-icons, list, search, empty
+NTB_HOMEPAGE_LAYOUT=categories
+```
+
+### Default Navbar Display
+
+Control what appears in the top navigation:
+
+```bash
+# Options: default, bookmarked, frequent, none
+NTB_NAVBAR_DISPLAY=default
+```
+
+### Default Theme
+
+Set the default color theme:
+
+```bash
+# Options: dark, light, midnight, arctic, ocean, purple, cyberpunk, terminal, lightpurple, muteddark, solarized
+NTB_DEFAULT_THEME=dark
+```
+
+## Example Configurations
+
+### Corporate Branding Example
+
+```bash
+NTB_SITE_NAME=Acme Corp Network Tools
+NTB_SITE_TITLE=Acme Corp Network Tools
+NTB_SITE_DESCRIPTION=Internal networking utilities for Acme Corp IT team
+NTB_SITE_ICON=/acme-logo.svg
+NTB_DEFAULT_THEME=light
+NTB_HOMEPAGE_LAYOUT=list
+```
+
+### Minimalist Setup Example
+
+```bash
+NTB_SITE_NAME=NetUtils
+NTB_SITE_DESCRIPTION=Simple network utilities
+NTB_DEFAULT_THEME=muteddark
+NTB_HOMEPAGE_LAYOUT=search
+NTB_NAVBAR_DISPLAY=none
+```
+
+## Docker Deployment
+
+When using Docker, pass environment variables with the `-e` flag or use a `.env` file:
+
+```bash
+docker run -p 5000:5000 \
+  -e NTB_SITE_NAME="My Network Tools" \
+  -e NTB_DEFAULT_THEME="light" \
+  lissy93/networking-toolbox
+```
+
+Or with docker-compose:
+
+```yaml
+services:
+  networking-toolbox:
+    image: lissy93/networking-toolbox
+    ports:
+      - "5000:5000"
+    environment:
+      - NTB_SITE_NAME=My Network Tools
+      - NTB_DEFAULT_THEME=light
+      - NTB_SITE_ICON=/custom-logo.svg
+    volumes:
+      - ./static:/app/static  # For custom logo
+```
+
+## Notes
+
+- All environment variables must be prefixed with `NTB_` to be accessible
+- Changes require an application restart to take effect
+- The managed instance at [networking-toolbox.as93.net](https://networking-toolbox.as93.net) uses the default values
+- User preferences set through the UI take precedence over these defaults
+- Invalid values will fallback to the default settings
+
+

.github/workflows/report-tests.yml

@@ -12,6 +12,7 @@ permissions:
   contents: read
   checks: write    # For test reporting
   pull-requests: write  # For PR comments
+  actions: read
 
 jobs:
   report:

src/lib/components/furniture/Header.svelte

@@ -1,5 +1,6 @@
 <script lang="ts">
   import { site } from '$lib/constants/site';
+  import { SITE_ICON } from '$lib/config/customizable-settings';
   import Icon from '$lib/components/global/Icon.svelte';
   import GlobalSearch from '$lib/components/global/GlobalSearch.svelte';
   import BurgerMenu from '$lib/components/furniture/BurgerMenu.svelte';
@@ -11,6 +12,8 @@
 
   let globalSearchRef: GlobalSearch;
   let shortcutsDialogRef: ShortcutsDialog;
+
+  const hasCustomLogo = SITE_ICON && SITE_ICON.trim() !== '';
 </script>
 
 <header class="header">
@@ -19,7 +22,11 @@
       <div class="logo">
         <div class="logo-icon">
           <a href="/" aria-label="Home">
-            <Icon name="networking" size="lg" />
+            {#if hasCustomLogo}
+              <img src={SITE_ICON} alt={site.name} class="logo-image" />
+            {:else}
+              <Icon name="networking" size="lg" />
+            {/if}
           </a>
         </div>
         <div>
@@ -72,6 +79,13 @@
     flex-shrink: 0; // Prevent logo from shrinking
     background: var(--bg-secondary);
     z-index: 1;
+
+    .logo-image {
+      width: 2.5rem;
+      height: 2.5rem;
+      object-fit: contain;
+      display: block;
+    }
   }
 
   .header-actions {

src/lib/components/page-specific/about/DeployingSection.svelte

@@ -16,7 +16,8 @@
     <code>docker run -p 8080:8080 lissy93/networking-toolbox</code>
   </div>
   <p>
-    You can also checkout our <a href="https://github.com/Lissy93/networking-toolbox/blob/main/docker-compose.yml"
+    You can also checkout our
+    <a href="https://github.com/Lissy93/networking-toolbox/blob/main/docker-compose.yml"
       ><code>docker-compose.yml</code></a
     >, using the
     <a href="https://hub.docker.com/r/lissy93/networking-toolbox"><code>lissy93/networking-toolbox</code></a> image from
@@ -42,9 +43,55 @@
   <h3>Option #4 - Source</h3>
   <p>
     If you want to make any changes before deploying, or want to host it on any other platform not already covered
-    above, then you can easily do so, by compiling the app from source. We've dot detailed <a href="/about/building"
-      >Building Instructions</a
-    >, or you can check out the docs in the repo.
+    above, then you can easily do so, by compiling the app from source. It's very easy, and we've dot detailed
+    <a href="/about/building">Building Instructions</a>, or you can check out the docs in the repo.
+  </p>
+</section>
+
+<section>
+  <h2>Customizing</h2>
+  <p>You can customize the branding of your instance, by setting a few environment variables. All are optional.</p>
+  <ul>
+    <li><code>NTB_SITE_NAME</code> - Change sitename</li>
+    <li><code>NTB_SITE_DESCRIPTION</code> - Change site tagline</li>
+    <li><code>NTB_SITE_ICON</code> - Set site icon</li>
+    <li><code>NTB_HOMEPAGE_LAYOUT</code> - Set homepage layout</li>
+    <li><code>NTB_NAVBAR_DISPLAY</code> - Set navbar display option</li>
+    <li><code>NTB_DEFAULT_THEME</code> - Set default theme</li>
+    <li><code>NTB_DEFAULT_LANGUAGE</code> - Set default lang</li>
+  </ul>
+
+  <p>
+    For examples on how to apply these, take a look at
+    <a href="https://github.com/Lissy93/networking-toolbox/blob/main/.github/docs/app-customization.md">these docs</a>.
+  </p>
+</section>
+
+<section>
+  <h2>Terms</h2>
+  <p>Your only obligations are:</p>
+  <ul>
+    <li>
+      Preserve the MIT license. You can view this on the <a href="/about/license">Licensing Page</a>
+    </li>
+    <li>
+      You can not hold the author liable for any damages, and you understand that the software is provided "as is" with
+      no warranties
+    </li>
+    <li>
+      Not use the name "Networking Toolbox" or the logo commercially to build a competing product, without prior
+      permission (you can rebrand it though)
+    </li>
+    <li>Not use the software for anything illegal, harmful, offensive, or otherwise objectionable</li>
+  </ul>
+  <p>
+    Beyond that, you're free to use it however you want, for personal or commercial use. You can rebrand it, or use
+    parts of the code in your own projects and edit anything.
+  </p>
+  <p>
+    If you've found the project helpful, and want to support us, considering <a
+      href="https://github.com/sponsors/Lissy93">sponsoring us</a
+    > on GitHub. It always means the world to me, and helps cover ongoing running costs 🩷
   </p>
 </section>
 

src/lib/config/customizable-settings.ts

@@ -0,0 +1,54 @@
+/**
+ * Customizable Settings
+ *
+ * This file provides default settings that can be overridden via environment variables.
+ * All environment variables must be prefixed with NTB_ to be accessible.
+ *
+ * For self-hosted instances, these can be customized by setting the corresponding
+ * environment variables. The managed instance will use the defaults.
+ */
+
+import { env } from '$env/dynamic/public';
+import type { HomepageLayoutMode } from '$lib/stores/homepageLayout';
+import type { NavbarDisplayMode } from '$lib/stores/navbarDisplay';
+import type { ThemeOption } from '$lib/stores/theme';
+
+// Site Branding
+export const SITE_NAME = env.NTB_SITE_NAME;
+export const SITE_TITLE = env.NTB_SITE_TITLE;
+export const SITE_DESCRIPTION = env.NTB_SITE_DESCRIPTION;
+
+/**
+ * Logo/icon to display in the navbar, specified as a path to an image
+ */
+export const SITE_ICON = env.NTB_SITE_ICON ?? '';
+
+/**
+ * Default homepage layout
+ * Options: 'categories', 'default', 'minimal', 'carousel', 'bookmarks', 'small-icons', 'list', 'search', 'empty'
+ */
+export const DEFAULT_HOMEPAGE_LAYOUT: HomepageLayoutMode =
+  (env.NTB_HOMEPAGE_LAYOUT as HomepageLayoutMode) ?? 'categories';
+
+/**
+ * Default navbar display mode
+ * Options: 'default', 'bookmarked', 'frequent', 'none'
+ */
+export const DEFAULT_NAVBAR_DISPLAY: NavbarDisplayMode = (env.NTB_NAVBAR_DISPLAY as NavbarDisplayMode) ?? 'default';
+
+/**
+ * Default theme
+ * Options: 'dark', 'light', 'midnight', 'arctic', 'ocean', 'purple', 'cyberpunk', 'terminal', 'lightpurple', 'muteddark', 'solarized'
+ */
+export const DEFAULT_THEME: ThemeOption = (env.NTB_DEFAULT_THEME as ThemeOption) ?? 'dark';
+
+/**
+ * Default language
+ * Options: 'en', 'es', 'fr', 'de', etc.
+ */
+export const DEFAULT_LANGUAGE = env.NTB_DEFAULT_LANGUAGE ?? 'en';
+
+/**
+ * Primary color (for default theme). Specified as a hex code.
+ */
+export const PRIMARY_COLOR = env.NTB_PRIMARY_COLOR ?? '';

src/lib/constants/site.ts

@@ -1,10 +1,12 @@
+import { SITE_NAME, SITE_TITLE, SITE_DESCRIPTION } from '$lib/config/customizable-settings';
+
 export const site = {
-  name: 'Networking Toolbox',
-  title: 'Networking Toolbox',
+  name: SITE_NAME || 'Networking Toolbox',
+  title: SITE_TITLE || 'Networking Toolbox',
   description: 'A free set of online tools to help with IP addressing and subnetting.',
   longDescription:
     'Comprehensive IP address calculator with subnet calculations, CIDR conversion, IP format conversion, and network reference tools.',
-  heroDescription: 'Your companion for all-things networking',
+  heroDescription: SITE_DESCRIPTION || 'Your companion for all-things networking',
   keywords: 'IP calculator, subnet calculator, CIDR converter, network tools, IP tools, networking',
   url: 'https://networking-toolbox.as93.net',
   image: 'https://networking-toolbox.as93.net/og-image.png',
@@ -34,8 +36,6 @@ export const author = {
   url: 'https://aliciasykes.com',
   portfolio: 'https://as93.net',
   sponsor: 'https://github.com/sponsors/lissy93',
-  // avatar: 'https://i.ibb.co/678bNCjD/alicia-sykes-184-Edit.jpg',
-  // avatar: 'https://apps.aliciasykes.com/profile.jpg',
   avatar: 'https://i.ibb.co/Q7XTgybB/DSC-0444-2.jpg',
 };
 

src/lib/stores/homepageLayout.ts

@@ -1,5 +1,6 @@
 import { writable } from 'svelte/store';
 import { browser } from '$app/environment';
+import { DEFAULT_HOMEPAGE_LAYOUT } from '$lib/config/customizable-settings';
 
 export type HomepageLayoutMode =
   | 'default'
@@ -69,18 +70,26 @@ export const homepageLayoutOptions: HomepageLayoutOption[] = [
   },
 ];
 
+// Validate that a layout mode is valid
+function isValidLayout(layout: string | null): boolean {
+  if (!layout) return false;
+  return homepageLayoutOptions.some((option) => option.id === layout);
+}
+
 // Get initial value from localStorage (runs immediately on import)
 function getInitialLayout(): HomepageLayoutMode {
+  // Validate DEFAULT_HOMEPAGE_LAYOUT, fallback to 'categories' if invalid
+  const validDefault = isValidLayout(DEFAULT_HOMEPAGE_LAYOUT) ? DEFAULT_HOMEPAGE_LAYOUT : 'categories';
+
   if (browser) {
     try {
       const stored = localStorage.getItem('homepage-layout');
-      const isValidMode = homepageLayoutOptions.some((option) => option.id === stored);
-      return isValidMode ? (stored as HomepageLayoutMode) : 'categories';
+      return isValidLayout(stored) ? (stored as HomepageLayoutMode) : validDefault;
     } catch {
-      return 'categories';
+      return validDefault;
     }
   }
-  return 'categories';
+  return validDefault;
 }
 
 function createHomepageLayoutStore() {