mirror of
https://github.com/lissy93/networking-toolbox.git
synced 2026-11-20 21:23:10 +03:00
Implemented re-branding option for self-hosted users
This commit is contained in:
1 parent
b57cfde993
commit
7fbb30efdf
12 files changed
+305
-24
No files matched your search
@@ -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
|
||||
|
||||
|
||||
@@ -12,6 +12,7 @@ permissions:
|
||||
contents: read
|
||||
checks: write # For test reporting
|
||||
pull-requests: write # For PR comments
|
||||
actions: read
|
||||
|
||||
jobs:
|
||||
report:
|
||||
|
||||
@@ -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>
|
||||
|
||||
|
||||
@@ -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 ?? '';
|
||||
@@ -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',
|
||||
};
|
||||
|
||||
|
||||
@@ -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() {
|
||||
|
||||
@@ -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
@@ -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
|
||||
|
||||
@@ -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
@@ -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
@@ -10,5 +10,6 @@ export default defineConfig({
|
||||
bundleName: "networking-toolbox",
|
||||
uploadToken: process.env.CODECOV_TOKEN,
|
||||
}),
|
||||
]
|
||||
],
|
||||
envPrefix: ['VITE_', 'PUBLIC_', 'NTB_'],
|
||||
});
|
||||
Reference in new issue
Block a user