Implemented re-branding option for self-hosted users

This commit is contained in:
Alicia Sykes committed 2025-10-12 18:55:31 +01:00
1 parent b57cfde993
commit 7fbb30efdf
12 files changed
+305 -24

No files matched your search

+134
View File
@@ -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
+1
View File
@@ -12,6 +12,7 @@ permissions:
contents: read
checks: write # For test reporting
pull-requests: write # For PR comments
actions: read
jobs:
report:
+15 -1
View File
@@ -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 {
@@ -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>
+54
View File
@@ -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 ?? '';
+5 -5
View File
@@ -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',
};
+13 -4
View File
@@ -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() {
+11 -4
View File
@@ -1,5 +1,6 @@
import { writable } from 'svelte/store';
import { browser } from '$app/environment';
import { DEFAULT_NAVBAR_DISPLAY } from '$lib/config/customizable-settings';
export type NavbarDisplayMode = 'default' | 'bookmarked' | 'frequent' | 'none';
@@ -35,18 +36,24 @@ export const navbarDisplayOptions: NavbarDisplayOption[] = [
},
];
// Validate that a navbar display mode is valid
function isValidNavbarDisplay(mode: string | null): boolean {
if (!mode) return false;
return navbarDisplayOptions.some((option) => option.id === mode);
}
// Get initial value from localStorage (runs immediately on import)
function getInitialNavbarDisplay(): NavbarDisplayMode {
const validDefault = isValidNavbarDisplay(DEFAULT_NAVBAR_DISPLAY) ? DEFAULT_NAVBAR_DISPLAY : 'default';
if (browser) {
try {
const stored = localStorage.getItem('navbar-display');
const isValidMode = navbarDisplayOptions.some((option) => option.id === stored);
return isValidMode ? (stored as NavbarDisplayMode) : 'default';
return isValidNavbarDisplay(stored) ? (stored as NavbarDisplayMode) : validDefault;
} catch {
return 'default';
return validDefault;
}
}
return 'default';
return validDefault;
}
function createNavbarDisplayStore() {
+10 -4
View File
@@ -1,5 +1,6 @@
import { writable } from 'svelte/store';
import { browser } from '$app/environment';
import { DEFAULT_THEME } from '$lib/config/customizable-settings';
export type ThemeOption = string;
@@ -176,8 +177,14 @@ export const themes: Theme[] = [
},
];
function isValidTheme(theme: string | null) {
if (!theme) return false;
return themes.some((t) => t.id === theme && t.available);
}
function createThemeStore() {
const { subscribe, set, update } = writable<ThemeOption>('dark');
const defaultTheme = isValidTheme(DEFAULT_THEME) ? DEFAULT_THEME : 'dark';
const { subscribe, set, update } = writable<ThemeOption>(defaultTheme);
return {
subscribe,
@@ -186,8 +193,7 @@ function createThemeStore() {
init: () => {
if (browser) {
const saved = localStorage.getItem(STORAGE_KEY);
const isValidTheme = themes.some((t) => t.id === saved && t.available);
const initialTheme = isValidTheme ? (saved as ThemeOption) : 'dark';
const initialTheme = isValidTheme(saved) ? (saved as ThemeOption) : defaultTheme;
set(initialTheme);
@@ -196,7 +202,7 @@ function createThemeStore() {
return initialTheme;
}
return 'dark';
return defaultTheme;
},
// Set theme and persist to localStorage
+3
View File
@@ -79,6 +79,9 @@ const config = {
paths: {
base: process.env.BASE_URL || process.env.BASE_PATH || '',
},
env: {
publicPrefix: 'NTB_',
},
prerender: {
entries: ['/', '/sitemap'] ,
handleHttpError: 'warn',
+6 -1
View File
@@ -1,8 +1,13 @@
import '@testing-library/jest-dom/vitest';
import { beforeAll, afterEach, afterAll } from 'vitest';
import { beforeAll, afterEach, afterAll, vi } from 'vitest';
import { setupServer } from 'msw/node';
import { http, HttpResponse } from 'msw';
// Mock SvelteKit env module for tests
vi.mock('$env/dynamic/public', () => ({
env: {}
}));
// MSW server for mocking API calls
export const server = setupServer(
// Default handlers
+2 -1
View File
@@ -10,5 +10,6 @@ export default defineConfig({
bundleName: "networking-toolbox",
uploadToken: process.env.CODECOV_TOKEN,
}),
]
],
envPrefix: ['VITE_', 'PUBLIC_', 'NTB_'],
});