Author	Nejat Hakan
eMail	nejat.hakan@outlook.de
PayPal Me	https://paypal.me/nejathakan

Personal Dashboard - Organizr

Introduction to Personal Dashboards and Organizr

Welcome to the world of personal dashboards! In an era where we interact with a multitude of web services, applications, and data streams daily, managing and accessing them efficiently can become a daunting task. A personal dashboard aims to solve this by providing a centralized, customizable interface to all your important digital resources. Organizr is a popular, powerful, and versatile tool specifically designed for this purpose, especially favored within the self-hosting community. This introductory section will explore the concept of personal dashboards, introduce Organizr, and set the stage for your journey into creating a more organized digital life. We'll delve into why you might want one, what Organizr brings to the table, and how it can become the command center for your self-hosted services and beyond.

What is a Personal Dashboard?

A personal dashboard is essentially a web-based, unified interface that brings together various services, information feeds, and applications into a single, easily accessible view. Think of it as the homepage for your digital life or your self-hosted ecosystem. Instead of juggling multiple browser tabs, remembering numerous URLs, or logging into various services independently, a dashboard centralizes access and often provides at-a-glance information.

Core Purposes and Benefits:

Centralization: The most significant benefit is having a single point of entry for all your frequently used services. This could include your media servers (Plex, Jellyfin), download clients (SABnzbd, NZBGet), home automation interfaces (Home Assistant), network monitoring tools (Pi-hole, Uptime Kuma), and even external websites you visit often.
Accessibility: By hosting your dashboard, you can access your services from any device with a web browser, whether you're at home or (if configured securely) on the go.
Customization: Personal dashboards are highly customizable. You can tailor the layout, appearance, and the specific services integrated to perfectly match your needs and preferences. This includes theming, organizing services into categories or tabs, and deciding what information is displayed upfront.
Efficiency and Productivity: By reducing the friction of accessing different services, dashboards save you time and mental effort. Important information can be surfaced directly on the dashboard, eliminating the need to navigate into each application.
Simplified Management: For self-hosters, a dashboard can greatly simplify the management of a growing collection of services. It provides an overview and quick access, making it easier to monitor and interact with your setup.
User Management: Many dashboard solutions, including Organizr, offer user management features, allowing you to share access with family or friends while controlling what each user can see or do.

Examples of What Can Be Integrated:

The possibilities are vast, but common integrations include:

Media Services: Plex, Jellyfin, Emby, Sonarr, Radarr, Lidarr, Bazarr, Tautulli.
Download Clients: SABnzbd, NZBGet, qBittorrent, Transmission.
Network Utilities: Pi-hole, AdGuard Home, NGINX Proxy Manager, Uptime Kuma, router admin pages.
Home Automation: Home Assistant, Node-RED.
Productivity & Information: Calendars, weather widgets, news feeds, system monitoring dashboards (e.g., Grafana).
Communication: Links to chat applications or webmail.
File Management: Web-based file explorers like FileBrowser.
Any web-accessible service: If it has a web interface, chances are you can integrate it into your dashboard, often via an iFrame or a simple link.

A personal dashboard, therefore, is more than just a collection of links; it's a dynamic, personalized portal that streamlines your digital interactions and enhances your control over your self-hosted environment.

Workshop: Conceptualizing Your Ideal Dashboard

Goal: To help you identify your needs, list the services you want to integrate, and begin envisioning your perfect personal dashboard. This foundational step is crucial for building a dashboard that truly serves your purposes.

Steps:

List Your Current Self-Hosted Services:
- Open a text editor or grab a piece of paper.
- Carefully list every self-hosted application or service you currently run.
- For each service, note down its primary function and how you access it (e.g., Plex - Media Streaming - http://192.168.1.10:32400/web).
- Example:
  - Sonarr - TV Show Management - http://192.168.1.10:8989
  - Radarr - Movie Management - http://192.168.1.10:7878
  - Pi-hole - Network Ad-blocker - http://192.168.1.11/admin
  - Home Assistant - Home Automation - http://192.168.1.12:8123
List Frequently Visited Web Services (Non-Self-Hosted):
- Think about the websites and online services you access regularly that are not self-hosted.
- These could be news sites, social media, cloud services, forums, etc.
- Example:
  - Tech News Site - https://www.exampletechnews.com
  - Cloud Storage - https://drive.google.com
  - Favorite Forum - https://forum.example.com
Identify Pain Points in Accessing These Services:
- Reflect on your current workflow. What frustrates you?
- Do you constantly type IP addresses and port numbers?
- Do you have too many bookmarks?
- Is it hard to remember where everything is?
- Do you wish you could see key information (e.g., download progress, upcoming media) without opening each app?
- Example Pain Points:
  - "Forgetting the port number for Radarr."
  - "Having 10+ bookmarks for my local services."
  - "Wanting to quickly check if a download finished without opening SABnzbd fully."
  - "My family members can't easily find Plex; they always ask me for the link."
Sketch a Rough Layout of Your Ideal Dashboard:
- This doesn't need to be a work of art. A simple block diagram or a list of desired sections is fine.
- Think about how you'd like to group services. Perhaps by category (Media, Downloads, Utilities) or by frequency of use.
- Consider what information you'd like to see on the "front page" or main view.
- Example Sketch Idea:
  - Main View/Homepage:
    - Weather Widget
    - Sonarr: Upcoming TV Shows
    - Radarr: Recently Added Movies
    - SABnzbd: Current Download Speed & Queue
  - Tabs/Categories:
    - Media: Plex, Tautulli
    - Arr Apps: Sonarr, Radarr, Lidarr, Bazarr
    - Downloads: SABnzbd, qBittorrent
    - Network: Pi-hole, Router Admin, NGINX Proxy Manager
    - Utilities: Uptime Kuma, Portainer
    - External Links: News Site, Favorite Forum

By completing this conceptualization workshop, you'll have a much clearer vision of what you want to achieve with Organizr. This "blueprint" will guide your setup and customization choices in the subsequent sections.

Introducing Organizr

Organizr stands out as a highly popular and feature-rich web application designed to be the ultimate homepage for your server. Developed with self-hosters in mind, it provides a sleek, unified interface to manage and access all your web-based applications and services. It's more than just a bookmark manager; it's a comprehensive dashboard environment.

Core Features and Strengths:

NGINX Backend: Organizr is built on top of NGINX, a powerful and efficient web server. This allows Organizr to not only serve its own interface but also to intelligently handle requests, and even act as a basic reverse proxy or authentication gateway for other services in more advanced setups.
Tabbed Interface: One of Organizr's defining features is its tabbed browsing experience. You can open multiple services within Organizr, each in its own tab, similar to how a web browser works. This keeps everything contained within a single browser window and a unified user interface.
iFrame Integration: Most services are integrated via iFrames. This means the actual interface of the service (e.g., Sonarr's UI) is displayed directly within an Organizr tab. This provides a seamless experience, though it can sometimes be limited by services that prevent iFraming (due to X-Frame-Options headers, which we'll discuss later).
Homepage Items: Beyond tabs, Organizr allows you to add "Homepage Items." These are widgets that can display specific information from your services directly on the Organizr homepage, giving you an at-a-glance overview without needing to open the full service in a tab. Examples include upcoming media from Sonarr/Radarr, download speeds from SABnzbd/NZBGet, or server status information.
Single Sign-On (SSO) Capabilities: Organizr can act as an SSO provider. You can configure it to use its own user database, or integrate with external authentication providers like Plex, Emby, or Jellyfin. Once logged into Organizr, it can potentially pass authentication to other services, simplifying the login process across your ecosystem. This is an advanced feature but incredibly powerful.
User Management and Permissions: Create multiple user accounts and assign them to groups. Each group can have different permissions, controlling which tabs, homepage items, or settings users can access. This is great for family setups or sharing access with friends.
Theming and Customization: Organizr offers extensive theming options. You can choose from pre-built themes, download themes from a marketplace, or even create your own with custom CSS. This allows you to personalize the look and feel to your exact liking.
API Access: Organizr has an API, enabling integration with other tools and scripts for more advanced automation or information retrieval.
Active Development and Community: Organizr has a dedicated developer and a vibrant community (especially on Discord). This means ongoing updates, new features, and readily available support if you run into issues or have questions.

Why Choose Organizr?

While other dashboard solutions exist (e.g., Heimdall, Homer, SUI), Organizr offers a unique blend of features:

Power vs. Simplicity: It's powerful enough for advanced users with its NGINX backend and SSO capabilities, yet accessible enough for beginners to set up a basic dashboard quickly.
Integrated Experience: The tabbed iFrame approach provides a more integrated feel than simple link-based dashboards.
Focus on Self-Hosted Services: Many of its homepage items and integrations are tailored specifically for popular self-hosted applications.

Key Organizr Terminology:

Tab: A primary way to integrate a service. When you click a tab, the service's interface typically loads within an iFrame in the main content area of Organizr.
Homepage Item: A widget displayed on Organizr's main landing page (homepage). These provide quick summaries or direct information from integrated services.
SSO (Single Sign-On): A system allowing users to log in once and gain access to multiple related but independent software systems. Organizr can act as an SSO provider for services integrated with it.
Reverse Proxy: A server that sits in front of web servers and forwards client (e.g., web browser) requests to those web servers. Organizr itself uses NGINX and can be placed behind another reverse proxy (like NGINX Proxy Manager or Traefik) for SSL and easier public access.
iFrame (Inline Frame): An HTML element that allows an external webpage to be embedded within the current HTML document. This is how Organizr displays most services within its tabs.
X-Frame-Options: An HTTP response header that tells the browser whether it's allowed to render a page in a <frame>, <iframe>, <embed>, or <object>. This header is often the reason why some websites cannot be embedded in Organizr tabs.

Organizr aims to be the central nervous system for your self-hosted applications, providing a user-friendly, customizable, and powerful interface to manage your digital domain.

Workshop: Exploring the Organizr Demo

Goal: To familiarize yourself with Organizr's user interface, navigation, and core features by interacting with the official online demo.

Steps:

Access the Official Demo:
- Open your web browser.
- Navigate to the official Organizr website. You can usually find this by searching "Organizr GitHub" or "Organizr dashboard." The primary repository is often organizr/organizr. Look for a link to a live demo, often demo.organizr.app.
- Note: The exact URL for the demo might change over time, but it's typically linked from their official resources. For this workshop, let's assume you've found it.
Initial Exploration - Login and Homepage:
- The demo site might automatically log you in as a guest or present a login screen.
- If there's a login, use any provided demo credentials (often demo/demo or admin/admin).
- Once logged in (or if no login was required for the demo), observe the main homepage.
- Identify the different sections:
  - The top bar (usually with a search bar, settings icon, user icon).
  - The sidebar (where tabs are listed).
  - The main content area (which might display homepage items).
- Take note of any "Homepage Items" displayed. What information do they show? (e.g., System Info, Plex statistics, download client status).
Navigate Through Different Tabs:
- In the sidebar, click on various tabs that are pre-configured in the demo (e.g., Sonarr, Radarr, NZBGet, or other common self-hosted apps).
- Observe how the content in the main area changes to display the iFramed interface of the selected service.
- Notice how you can interact with these services within Organizr, just as if you had opened them in a separate browser tab.
- Try opening multiple tabs. See how Organizr manages them. Can you reorder them? (Usually yes, by dragging in the Tab Editor).
Explore Settings (Without Making Changes):
- Locate the settings icon (often a cogwheel or gear) in the top bar and click it.
- You'll be taken to Organizr's settings panel. This is where the real power of Organizr lies.
- Browse through the different settings categories on the left (e.g., Main, Customize, SSO, Homepage, Tabs, Users). Do not save any changes you make in the demo environment unless explicitly allowed or it's a guest-resettable demo.
- Under Customize -> Appearance, look at the theme options.
- Under Tabs -> Tab Editor, see how tabs are configured (Name, URL, Tab Type, Icon).
- Under Homepage -> Homepage Items, see the list of available items and their configurations.
- Under Users -> User Management, observe how users and groups might be set up.
Identify Three Appealing Features:
- Based on your exploration, think about what aspects of Organizr you find most useful or interesting for your own potential setup.
- Write down at least three features. For example:
  1. "The ability to see Sonarr's upcoming shows directly on the homepage."
  2. "The clean, tabbed interface that keeps all my services in one browser window."
  3. "The extensive theming options to make it look exactly how I want."

By spending some time with the demo, you'll gain a practical understanding of what Organizr offers and how it functions. This hands-on experience will make the process of installing and configuring your own instance much smoother.

1. Basic Setup and Configuration

This section will guide you through the essential first steps to get your own instance of Organizr up and running. We'll cover the necessary prerequisites, walk through the installation process using Docker Compose (the recommended method), navigate the initial configuration wizard, and finally, add your first few services as tabs to begin building your personalized dashboard. By the end of this section, you will have a functional Organizr instance, ready for further customization. We'll focus on creating a solid foundation, ensuring you understand each step along the way.

Prerequisites for Installing Organizr

Before diving into the installation of Organizr, it's crucial to ensure your system meets the necessary requirements and that you have a foundational understanding of certain concepts. This preparation will make the installation process smoother and help you troubleshoot any potential issues.

Hardware Requirements:

Organizr itself is quite lightweight. The primary resource consumption will often come from the services you integrate into it, rather than Organizr itself. However, here are some general guidelines for the machine that will host Organizr:

CPU: A modern multi-core CPU is recommended. Even a low-power CPU like those found in Raspberry Pis (e.g., Raspberry Pi 4 with 4GB+ RAM) or small form-factor PCs (NUCs) is generally sufficient for Organizr and a moderate number of services. If you plan to run many resource-intensive services alongside Organizr on the same machine, you'll need a more powerful CPU.
RAM:
- Minimum: 1GB of RAM dedicated to the system if Organizr is one of very few services.
- Recommended: 2GB-4GB of RAM for the host system if running Organizr alongside a few other Docker containers. If you're running many services, especially media servers or databases, aim for 8GB+ for the entire system. Organizr's Docker container itself usually consumes a modest amount of RAM (e.g., 100-300MB).
Storage:
- Organizr's configuration files are small (a few megabytes).
- You'll need enough disk space for the Docker image (a few hundred MBs) and for the operating system.
- A 20-30GB drive or partition for the OS and Docker containers is a good starting point. SSDs are highly recommended for better performance, especially for Docker operations.
Network: A stable network connection (Ethernet preferred over Wi-Fi for servers) is essential.

Software Requirements:

Operating System (OS):
- Organizr can run on various operating systems since it's typically deployed via Docker.
- Linux: Highly recommended. Distributions like Ubuntu Server (LTS versions are great), Debian, CentOS, or Fedora are excellent choices. Most self-hosting enthusiasts prefer Linux for its stability, performance, and control.
- Windows: Possible with Docker Desktop for Windows. Performance might not be as optimal as on Linux for server applications.
- macOS: Possible with Docker Desktop for Mac. Similar considerations as Windows.
- This guide will primarily focus on a Linux-based setup (specifically Ubuntu Server) as it's the most common environment for self-hosting.
Docker and Docker Compose:
- Docker: This is a platform for developing, shipping, and running applications in containers. Containers package up an application with all its dependencies, ensuring it runs consistently across different environments. Organizr provides an official Docker image, which is the easiest and most recommended way to install and manage it.
- Docker Compose: This is a tool for defining and running multi-container Docker applications. You use a YAML file (docker-compose.yml) to configure your application's services, networks, and volumes. It simplifies the management of Docker containers, especially when you have persistent data or specific networking needs.
- Why Docker?
  - Isolation: Organizr runs in its own isolated environment, preventing conflicts with other software on your system.
  - Portability: Easy to move your Organizr setup to another machine if needed.
  - Reproducibility: Your setup is defined in code (the docker-compose.yml file), making it easy to recreate.
  - Simplified Updates: Updating Organizr is often as simple as pulling the new Docker image and restarting the container.
  - Dependency Management: All dependencies are handled within the container, so you don't need to install NGINX or PHP directly on your host system.

Basic Understanding of Networking:

A fundamental grasp of basic networking concepts will be very helpful:

IP Addresses:
- Local IP Address: The address of your server on your local network (e.g., 192.168.1.100). You'll need this to access Organizr initially.
- Public IP Address: The address your ISP assigns to your home network. Relevant if you plan to access Organizr from outside your home network (requires port forwarding and ideally a reverse proxy and domain name).
Ports: Network ports are like virtual doors on your server that services listen on. For example, web servers typically use port 80 (HTTP) and 443 (HTTPS). When you run Organizr in Docker, you'll map a port on your host machine to a port inside the Organizr container (e.g., mapping host port 8080 to container port 80). You'd then access Organizr via http://<your-server-ip>:8080.
DNS (Domain Name System): Translates human-readable domain names (like www.google.com) into IP addresses. Relevant if you plan to use a domain name for Organizr.
Firewall: Software or hardware that controls incoming and outgoing network traffic. You might need to configure your firewall to allow access to the port Organizr is running on.

Having these prerequisites in place and a basic understanding of the concepts will set you up for a successful Organizr installation. The next sub-section will guide you through setting up the Docker environment itself.

Workshop: Setting Up Your Docker Environment

Goal: To ensure Docker and Docker Compose are correctly installed and functional on your chosen server operating system, preparing it for Organizr deployment. This workshop will use Ubuntu Server LTS as the example OS.

Steps:

Choose and Prepare Your Operating System:
- If you haven't already, install a Linux distribution on your server. Ubuntu Server 22.04 LTS (Long Term Support) is an excellent choice due to its stability and extensive community support.
- Ensure your OS is up to date:
```
sudo apt update
sudo apt upgrade -y
```
- It's also good practice to set a static IP address for your server on your local network. This can usually be done via your router's DHCP reservation settings or by configuring netplan on Ubuntu Server. For this workshop, we'll assume your server has a consistent IP address you can reach.
Install Docker Engine:
- Docker provides official installation scripts and packages. It's generally recommended to use Docker's official repositories for the latest versions.
- a. Set up Docker's apt repository:
```
# Add Docker's official GPG key:
sudo apt-get update
sudo apt-get install -y ca-certificates curl gnupg
sudo install -m 0755 -d /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg
sudo chmod a+r /etc/apt/keyrings/docker.gpg

# Add the repository to Apt sources:
echo \
  "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu \
  $(. /etc/os-release && echo "$VERSION_CODENAME") stable" | \
  sudo tee /etc/apt/sources.list.d/docker.list > /dev/null
sudo apt-get update
```
- b. Install Docker packages:
```
sudo apt-get install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin
```
  - docker-ce: Docker Community Edition (the engine itself).
  - docker-ce-cli: Docker command-line interface.
  - containerd.io: A core container runtime.
  - docker-buildx-plugin: For advanced build capabilities (good to have).
  - docker-compose-plugin: Integrates Docker Compose into the Docker CLI (allows using docker compose instead of docker-compose).
- c. (Optional but Recommended) Add your user to the docker group: To run Docker commands without sudo every time, add your current user to the docker group.
```
sudo usermod -aG docker ${USER}
```
  You will need to log out and log back in for this change to take effect, or you can run newgrp docker in your current terminal session to apply the new group membership immediately for that session.

Install Docker Compose (Standalone - if docker-compose-plugin was not available or preferred):

Note: If docker-compose-plugin was installed in the previous step, you can use docker compose (with a space) and can skip this step. If you prefer the standalone docker-compose (with a hyphen), or if the plugin wasn't available for your distribution, follow these steps. The standalone version is still widely used.
As of my last update, the Docker Compose V2 plugin (docker compose) is preferred. If you installed docker-compose-plugin in step 2b, you are good.

If you need the standalone docker-compose (v1, or v2 standalone):

# Check the latest release version on https://github.com/docker/compose/releases
LATEST_COMPOSE_VERSION=$(curl -s https://api.github.com/repos/docker/compose/releases/latest | grep '"tag_name":' | sed -E 's/.*"([^"]+)".*/\1/')
# Example: sudo curl -L "https://github.com/docker/compose/releases/download/v2.24.5/docker-compose-$(uname -s)-$(uname -m)" -o /usr/local/bin/docker-compose
# Replace v2.24.5 with $LATEST_COMPOSE_VERSION if the above command works, or manually check the version
# The command below constructs the URL using the detected latest version
sudo curl -L "https://github.com/docker/compose/releases/download/${LATEST_COMPOSE_VERSION}/docker-compose-$(uname -s)-$(uname -m)" -o /usr/local/bin/docker-compose
sudo chmod +x /usr/local/bin/docker-compose

Verify standalone installation: docker-compose --version

Verify Docker and Docker Compose Installation:
- Open a new terminal session (or log out and log back in if you added your user to the docker group).
- Check Docker version:
```
docker --version
```
  You should see output like: Docker version 20.10.17, build 100c701 (versions will vary).
- Check Docker Compose version (if using the plugin):
```
docker compose version
```
  Or, if using standalone docker-compose:
```
docker-compose --version
```
  You should see output like: Docker Compose version v2.12.2 (versions will vary).
Run a Simple "hello-world" Docker Container:
- This command downloads a test image and runs it in a container. It verifies that Docker is working correctly.
```
docker run hello-world
```
- You should see a message starting with "Hello from Docker!" This indicates that your Docker installation is operational. The message explains that Docker:
  1. Contacted the Docker daemon.
  2. The daemon pulled the "hello-world" image from Docker Hub (if not found locally).
  3. The daemon created a new container from that image.
  4. The daemon streamed the output from the container to your Docker client (your terminal).

Your Docker environment is now set up and ready! You have the necessary tools to download, configure, and run Organizr (and many other self-hosted applications) in a containerized fashion. This robust foundation is key to a stable and manageable self-hosting setup.

Installing Organizr using Docker Compose

With Docker and Docker Compose installed and verified, we can now proceed to install Organizr. Using Docker Compose is highly recommended as it allows us to define Organizr's configuration (like port mappings and volume mounts for persistent data) in a simple text file, making it easy to manage, backup, and recreate.

Understanding Docker Compose and docker-compose.yml Files:

Docker Compose (docker-compose.yml): This is a YAML (Yet Another Markup Language) file used to define and configure multi-container Docker applications. For Organizr, we'll typically define a single "service" (Organizr itself), but Docker Compose is powerful enough to manage complex applications with many interconnected services.
Key Components of a docker-compose.yml for Organizr:
- version: Specifies the version of the Docker Compose file format. '3.8' or '3.9' are common modern versions.
- services: This is the main section where you define each container you want to run. We'll have a service named organizr.
  - image: Specifies the Docker image to use. For Organizr, this is usually organizr/organizr:latest or a specific version tag. Using latest gets you the newest stable release, but pinning to a version can be safer for production to avoid unexpected breaking changes.
  - container_name: A friendly name for your container (e.g., organizr).
  - hostname: Sets the hostname inside the container.
  - restart: Defines the restart policy. unless-stopped or always are common choices, ensuring Organizr restarts automatically if it crashes or if the Docker daemon/server reboots.
  - ports: Maps ports from your host machine to ports inside the container. Organizr's internal NGINX server listens on port 80 by default within the container. You'll map a port on your host (e.g., 8999) to this container port (80). Format: "HOST_PORT:CONTAINER_PORT".
  - volumes: This is crucial for data persistence. Docker containers are ephemeral by default; if you remove a container, any data created inside it is lost unless stored in a volume. Volumes map a directory on your host machine to a directory inside the container. For Organizr, its configuration data is stored in /config inside the container. We'll map a host directory (e.g., ./organizr-config or /opt/organizr/config) to /config.
  - environment: Allows you to set environment variables inside the container. For Organizr, PUID (User ID) and PGID (Group ID) are important for setting file permissions on the mounted volume, and TZ (Timezone) ensures correct time display.

Step-by-Step Installation Guide:

Create a Project Directory:
It's good practice to create a dedicated directory on your server to hold your docker-compose.yml file and any related configuration data.
```
# Example: Create a directory in your user's home directory
mkdir ~/organizr-docker
cd ~/organizr-docker
```
Or, if you prefer a system-wide location (ensure you have appropriate permissions):
```
# sudo mkdir -p /opt/docker-apps/organizr # The -p flag creates parent directories if they don't exist
# cd /opt/docker-apps/organizr
```
For this guide, we'll assume ~/organizr-docker.
Determine PUID and PGID:
Organizr runs processes inside the container that write to the /config volume. To avoid permission issues on your host system, it's best to run these processes as your own user (or a dedicated service user) rather than root.
- Open a terminal on your Linux host and type id. You'll see output like:
```
uid=1000(yourusername) gid=1000(yourusername) groups=1000(yourusername),4(adm),20(dialout),...
```
- Note your uid (User ID) and gid (Group ID). In this example, both are 1000. These will be your PUID and PGID values.
Create the docker-compose.yml File:
Inside your project directory (~/organizr-docker), create a file named docker-compose.yml using a text editor like nano or vim.
```
nano docker-compose.yml
```
Paste the following content into the file. Remember to replace 1000 with your actual PUID and PGID, and adjust the host port and volume path if desired.
```
version: '3.8'

services:
  organizr:
    image: organizr/organizr:latest # You can pin to a specific version e.g., organizr/organizr:v2.1.900
    container_name: organizr
    hostname: organizr
    restart: unless-stopped
    ports:
      - "8999:80" # Host port 8999 mapped to container port 80. Access via http://<server_ip>:8999
    volumes:
      - ./config:/config # Maps a 'config' subdirectory in the current path to /config in the container
                        # Alternatively, use an absolute path like /srv/docker/organizr/config:/config
    environment:
      - PUID=1000        # Replace with your user's ID
      - PGID=1000        # Replace with your group's ID
      - TZ=Etc/UTC       # Replace with your timezone, e.g., America/New_York, Europe/London
                         # List of timezones: https://en.wikipedia.org/wiki/List_of_tz_database_time_zones
    networks: # Optional: if you want to connect Organizr to other containers on a custom Docker network
      - organizr_network # Example network name

# Optional: Define the custom network if you uncommented it above
# networks:
#   organizr_network:
#     driver: bridge
```
Explanation of the YAML content:
- version: '3.8': Defines the Compose file version.
- services:: Begins the definition of services (containers).
- organizr:: The name we give to our Organizr service.
- image: organizr/organizr:latest: Pulls the latest stable image from Docker Hub.
- container_name: organizr: Sets the name of the running container.
- hostname: organizr: Sets the hostname within the container. Useful if other containers on the same Docker network need to reach it by this name.
- restart: unless-stopped: The container will restart automatically unless it's explicitly stopped.
- ports: - "8999:80": This is critical. It maps port 8999 on your host machine to port 80 inside the Organizr container. You will access Organizr by navigating to http://<your_server_ip>:8999. You can change 8999 to any other available port on your host (e.g., 80 if it's free, or 8080).
- volumes: - ./config:/config: This maps a directory named config (which will be created in the same directory as your docker-compose.yml file, i.e., ~/organizr-docker/config) to the /config directory inside the Organizr container. This is where Organizr stores all its settings, database, logs, etc. This is essential for data persistence.
  - If you prefer an absolute path, you might use: - /opt/organizr/config:/config. Make sure the host directory /opt/organizr/config exists and has the correct permissions for the user defined by PUID/PGID.
- environment::
  - PUID=1000: Set to your user ID.
  - PGID=1000: Set to your group ID.
  - TZ=Etc/UTC: Set your correct timezone. This ensures logs and any time-sensitive features in Organizr display correctly.
- networks: - organizr_network: (Optional) If you plan to connect Organizr to other Docker containers (e.g., a database, or services it might interact with directly) on a custom Docker network, you define that here and also at the bottom of the file. For a basic setup, this is not strictly necessary as Docker provides a default bridge network.
Save the file and exit the text editor (in nano, press Ctrl+X, then Y, then Enter).
Start the Organizr Container:
Now, from your project directory (~/organizr-docker), run the following command:
```
docker compose up -d
# If you installed standalone docker-compose, use:
# docker-compose up -d
```
- docker compose up: This command starts the services defined in your docker-compose.yml file.
- -d: The "detached" flag. This runs the container in the background and returns you to the command prompt. Without -d, logs would stream to your terminal, and closing the terminal would stop the container.
Docker will now:
- Pull the organizr/organizr:latest image from Docker Hub (if it's not already on your system). This might take a few minutes depending on your internet speed.
- Create a network (if defined).
- Create the organizr container based on the image and your configuration.
- Start the container.
Verify the Container is Running:
You can check the status of your containers with:
```
docker ps
# Or, for more detail on a specific container:
# docker logs organizr
```
You should see organizr listed with a status like "Up X minutes" and the port mapping (e.g., 0.0.0.0:8999->80/tcp).
Accessing Organizr for the First Time:
Open a web browser on a computer on the same local network as your server. Navigate to: http://<your_server_ip>:<host_port>
- Replace <your_server_ip> with the actual local IP address of your server (e.g., 192.168.1.100).
- Replace <host_port> with the host port you specified in docker-compose.yml (e.g., 8999).
- So, the URL might be: http://192.168.1.100:8999
If everything is set up correctly, you should be greeted by the Organizr Setup Wizard.

Congratulations! You have successfully installed Organizr using Docker Compose. The config directory (~/organizr-docker/config in our example) now holds all your Organizr data. This method provides a clean, reproducible, and easily manageable way to run Organizr.

Workshop: Your First Organizr Deployment

Goal: To get a basic instance of Organizr running on your server using Docker Compose, accessible via your local network.

Pre-requisites:

Docker and Docker Compose are installed and working (as per the previous workshop).
You know the local IP address of your server.
You have terminal access to your server.

Steps:

Create a Project Directory on Your Server:
- Log into your server via SSH or open a terminal directly.
- Create a directory where you'll store your Organizr configuration. We'll call it my-organizr.
```
mkdir ~/my-organizr
cd ~/my-organizr
```
  - Explanation: This command creates a new directory named my-organizr inside your user's home directory (~) and then changes the current working directory into my-organizr. This keeps our Organizr files organized.
Determine Your User ID (PUID) and Group ID (PGID):
- In the terminal, run the id command:
```
id
```
- Look for uid=XXXX(yourusername) and gid=YYYY(yourgroupname). Note down the numerical values for XXXX (PUID) and YYYY (PGID). Often, these will both be 1000 for the first non-root user on a Linux system.
  - Explanation: These IDs will be used to ensure that files created by Organizr inside the Docker container (in its /config directory, which we'll map to our host) have the correct ownership on your host system, preventing permission errors.
Create the docker-compose.yml File:
- Inside the ~/my-organizr directory, create a new file named docker-compose.yml using a text editor. We'll use nano:
```
nano docker-compose.yml
```
- Copy and paste the following YAML configuration into the nano editor. Make sure to replace YOUR_PUID, YOUR_PGID, and Your/Timezone with your actual values.
```
version: '3.8' # Specifies the Docker Compose file format version.

services: # Defines the containers (services) to be run.
  organizr: # The name of our service.
    image: organizr/organizr:latest # Specifies the Docker image to use from Docker Hub. 'latest' pulls the most recent stable version.
    container_name: my-organizr-app # A friendly name for the running container.
    hostname: my-organizr-host # Sets the hostname inside the container.
    restart: unless-stopped # Policy for restarting the container (e.g., on system boot or if it crashes).
    ports:
      - "8088:80" # Maps port 8088 on the host machine to port 80 inside the container.
                    # You'll access Organizr via http://<server_ip>:8088
    volumes:
      - ./data:/config # Maps a subdirectory named 'data' (in the current path ~/my-organizr/data)
                        # to the /config directory inside the container. This stores Organizr's persistent data.
    environment:
      - PUID=YOUR_PUID # Replace YOUR_PUID with your actual User ID (e.g., 1000).
      - PGID=YOUR_PGID # Replace YOUR_PGID with your actual Group ID (e.g., 1000).
      - TZ=Your/Timezone # Replace with your timezone, e.g., America/Los_Angeles, Europe/Berlin.
                           # Find yours here: https://en.wikipedia.org/wiki/List_of_tz_database_time_zones
```
- Line-by-Line Explanation (Recap for Workshop Context):
  - version: '3.8': Standard practice to declare the Compose file syntax version.
  - services:: Parent key for all container definitions.
  - organizr:: A custom name for this specific service block (could be anything, but organizr is conventional).
  - image: organizr/organizr:latest: Tells Docker to download and use the official Organizr image tagged latest.
  - container_name: my-organizr-app: This name will appear when you list running Docker containers (docker ps).
  - hostname: my-organizr-host: Sets the internal hostname for the container.
  - restart: unless-stopped: Ensures Docker attempts to restart the container if it stops, unless you manually stop it.
  - ports: - "8088:80": We've chosen host port 8088. If 8088 is in use on your server, pick another (e.g., 8081, 9000). Organizr internally listens on port 80.
  - volumes: - ./data:/config: A directory named data will be created inside ~/my-organizr. All of Organizr's configuration will be saved here. If you delete the container but keep this data directory, your settings will persist.
  - environment:: Sets crucial environment variables inside the container.
    - PUID, PGID: For file permissions.
    - TZ: For correct time display in logs and UI.
- After pasting and modifying, save the file and exit nano:
  1. Press Ctrl+X.
  2. Press Y to confirm you want to save.
  3. Press Enter to save with the filename docker-compose.yml.
Launch Organizr:
- Ensure you are still in the ~/my-organizr directory (where your docker-compose.yml file is located).
- Run the following command to start Organizr in detached mode (in the background):
```
docker compose up -d
```
  (Or docker-compose up -d if you're using standalone Docker Compose).
- Explanation: docker compose up reads the docker-compose.yml file and starts the defined services. The -d flag runs the containers in the background, so you get your terminal prompt back. Docker will download the organizr/organizr image if it's not already present on your system.
Verify the Container is Running:
- Wait a minute or two for the image to download (if it's the first time) and the container to start.
- Check the status of your Docker containers:
```
docker ps
```
- You should see an entry for my-organizr-app (or whatever container_name you used). Look for:
  - IMAGE: organizr/organizr:latest
  - PORTS: 0.0.0.0:8088->80/tcp (or your chosen host port)
  - STATUS: Should say something like "Up X seconds/minutes"
  - NAMES: my-organizr-app
- Explanation: docker ps lists all actively running containers. The output confirms that your Organizr container is running and listening on the port you specified.
- You can also check the logs if you encounter issues:
```
docker logs my-organizr-app
```
Access Organizr in Your Web Browser:
- Open a web browser on your computer (which should be on the same network as your server).
- In the address bar, type: http://<your_server_ip>:8088
  - Replace <your_server_ip> with the actual IP address of your server (e.g., http://192.168.1.55:8088).
- You should be greeted by the Organizr Setup Wizard page.

You have now successfully deployed your first Organizr instance! The directory ~/my-organizr/data on your server now contains the persistent configuration for Organizr. In the next step, we'll go through the initial setup wizard.

Initial Organizr Configuration Wizard

Once you've successfully installed Organizr using Docker Compose and accessed it via your web browser for the first time (e.g., http://<your_server_ip>:<host_port>), you'll be greeted by the Organizr Setup Wizard. This wizard guides you through the essential initial configuration steps to get your dashboard operational. It's crucial to pay attention to these settings as they form the foundation of your Organizr experience.

Navigating the Setup Wizard Step-by-Step:

The wizard typically consists of several straightforward steps. Let's walk through them:

Step 1: Welcome & License Key

Welcome Message: A brief welcome to Organizr.
License Key: Organizr is free software, but it offers a licensing system primarily for supporting the developer and unlocking some cosmetic or minor features.
- You can obtain a free key from the Organizr website or their Discord server.
- You can also choose to "Continue without a license." For most functionalities, a license is not strictly required, especially for basic and intermediate use.
- Recommendation for now: You can click "Continue without a license" to proceed quickly. You can always add a license key later in the settings if you choose to get one.
Action: Make your choice regarding the license and click "Next" or "Continue."

Step 2: Database Type

Organizr needs a database to store its settings, user accounts, tab configurations, etc. You have two primary choices:
- SQLite (Default and Recommended for Beginners):
  - Pros: Simple, file-based database. No separate database server setup is required. The database file (organizr.db or similar) will be stored within your /config volume (e.g., ~/my-organizr/data/DB/). Easy to back up (just back up the whole /config directory).
  - Cons: Can be less performant under very heavy load or with a vast number of users/tabs, but for most personal setups, it's perfectly adequate.
- MySQL/MariaDB:
  - Pros: A more robust, server-based relational database system. Can offer better performance for very large or high-traffic Organizr instances. Allows the database to be hosted on a separate server if desired.
  - Cons: Requires you to have a separate MySQL or MariaDB server running and configured. You'll need to provide connection details (hostname, database name, username, password). Adds complexity to the setup.
Recommendation: For most users, especially when starting, SQLite is the best choice due to its simplicity. You can migrate to MySQL/MariaDB later if your needs evolve, though migration can be a manual process.
Action: Select "SQLite" and click "Next."

Step 3: Admin Account Creation

This is a critical step where you create the primary administrator account for your Organizr instance.
Username: Choose a username for your admin account (e.g., admin, or your preferred username).
Password: Create a strong, unique password. This password protects access to all your Organizr settings and, by extension, can control access to your integrated services. Use a password manager to generate and store a good password.
Confirm Password: Re-enter the password to ensure accuracy.
Email Address: Provide an email address. This can be used for password recovery (if configured) and notifications.
Registration Key (Optional): This is typically left blank unless you're setting up a system where new users need a specific key to register (more of an advanced feature for community setups).
Action: Fill in the details carefully, especially the password. Double-check for typos. Click "Next" or "Create Account."

Step 4: Personalization (May vary slightly by Organizr version)

Homepage Name: The name that appears in the browser tab title and potentially on the login page (e.g., "My Awesome Dashboard", "John's Server Hub").
Ping Interval: How often Organizr should "ping" or check the status of iFramed tabs to see if they are online. A moderate value (e.g., 60 seconds) is usually fine.
Other settings: There might be a few other minor personalization options. Review them and set them as desired. Defaults are often sensible.
Action: Customize these settings to your preference and click "Next."

Step 5: Finish

This is the final step of the wizard. It will confirm that the setup is complete.
You might see a summary of your settings or a prompt to log in.
Action: Click "Finish," "Go to Login," or a similar button.

First Login:

After completing the wizard, you'll usually be redirected to the Organizr login page.

Enter the administrator username and password you created in Step 3.
Click "Login."

You should now be logged into your brand new, personally hosted Organizr dashboard! It will likely look quite empty, perhaps with a default theme and no tabs configured yet. That's perfectly normal. The next step will be to start populating it with your services.

Understanding the Implications of Your Choices:

Database Choice: Sticking with SQLite simplifies your backup strategy significantly. If you chose MySQL/MariaDB, remember that your Organizr backup process must now also include backing up the separate MySQL/MariaDB database.
Admin Credentials: Guard your admin username and password carefully. Anyone with these credentials has full control over your Organizr instance.
Configuration Storage: All these settings, including your admin account details and the SQLite database (if chosen), are now stored within the volume you mapped in your docker-compose.yml file (e.g., ~/my-organizr/data/). This directory is now the heart of your Organizr installation.

You have now successfully navigated the initial setup wizard. Your Organizr instance is configured with its core settings and an administrator account, ready for you to start adding your services and customizing its appearance.

Workshop: Completing the Organizr Setup Wizard

Goal: To guide you step-by-step through Organizr's initial setup wizard, making informed choices for your new deployment.

Prerequisites:

You have successfully completed the "Your First Organizr Deployment" workshop.
Organizr is running and accessible in your web browser at http://<your_server_ip>:<your_chosen_host_port> (e.g., http://192.168.1.55:8088).
You see the Organizr Setup Wizard page.

Steps:

Access the Setup Wizard:
- If you're not already there, open your web browser and navigate to your Organizr URL (e.g., http://192.168.1.55:8088). You should be looking at the first page of the wizard.
Step 1: License Key:
- The page will present an option for a License Key.
- For this workshop, we will proceed without a license to keep things simple. You can always add one later.
- Action: Click the button that says "Continue without a license" (or similar wording).
- Significance: The license key primarily supports the developer and might unlock minor cosmetic features. Core functionality is available without it.
Step 2: Database Type Selection:
- Organizr will ask you to choose a database type: SQLite or MySQL/MariaDB.
- For simplicity and ease of management in this initial setup, we will choose SQLite.
- Action: Ensure "SQLite" is selected (it's usually the default). Click the "Next" button.
- Significance: SQLite stores the database as a file within your Organizr configuration directory (~/my-organizr/data/DB/ from our previous workshop). This simplifies backups as you only need to back up the main configuration directory. MySQL/MariaDB would require a separate database server.
Step 3: Administrator Account Creation:
- This is where you create your main admin account for Organizr.
- Username:
  - Enter a username. For this workshop, you can use admin, or choose your own.
  - Example: admin
- Password:
  - Enter a strong password. This is important! Use a mix of uppercase, lowercase, numbers, and symbols.
  - Example (for illustration only, use a real strong password!): MyP@sswOrd123!
- Confirm Password:
  - Re-enter the exact same password.
- Email Address:
  - Enter your email address. This can be useful for notifications or password recovery (if enabled later).
  - Example: your_email@example.com
- Registration Key:
  - Leave this field blank. It's not needed for a standard setup.
- Action: After filling in all fields, carefully review them, especially the password. Click the "Next" or "Create Account" button.
- Significance: This account will have full administrative privileges over your Organizr instance. Keep these credentials secure.
Step 4: Personalization (Content may vary slightly):
- Homepage Name:
  - Enter a name for your dashboard. This will appear in the browser title bar.
  - Example: My Self-Hosted Hub or [YourName]'s Dashboard
- Ping Interval (seconds):
  - This determines how often Organizr checks if your iFramed services are online. The default (e.g., 60 seconds) is usually fine.
  - Action: You can leave the default or adjust if you have a specific preference.
- Other Settings:
  - Review any other minor settings presented. Defaults are generally sensible for a start.
- Action: Once you've set your Homepage Name and reviewed other options, click "Next".
Step 5: Finish Setup:
- You should now see a confirmation page indicating that the setup is complete.
- Action: Click the "Finish", "Take me to my new Homepage!", or "Login" button.
Log In to Organizr:
- You will be redirected to the Organizr login page.
- Username: Enter the admin username you created in Step 3 (e.g., admin).
- Password: Enter the admin password you created in Step 3.
- Action: Click the "Login" button.

You should now be successfully logged into your Organizr dashboard! It will look quite bare, but it's fully functional and ready for you to start adding your services and customizing it. You've successfully configured the core of your personal dashboard.

Adding Your First Tabs and Services

With Organizr installed and the initial configuration wizard completed, your dashboard is live but empty. The next logical step is to start populating it by adding "Tabs." Tabs are the primary way you'll integrate and access your various self-hosted services and external websites through Organizr. Each tab essentially embeds or links to a specific web service.

Understanding Tab Types in Organizr:

Organizr offers several types of tabs, each serving a different purpose. The most common ones you'll use initially are:

iFrame Tab:
- Purpose: This is the most common tab type. It embeds the target web service directly within the Organizr interface using an HTML iFrame. This allows you to interact with the service (e.g., Sonarr, your router's admin page) without leaving Organizr.
- Pros: Provides a seamless, integrated experience.
- Cons: Some websites or web applications explicitly block being loaded in an iFrame using the X-Frame-Options or Content-Security-Policy HTTP headers. If a service blocks iFraming, it won't load correctly in an iFrame tab.
- Use Cases: Ideal for most self-hosted services that have a web UI and allow iFraming (e.g., Sonarr, Radarr, SABnzbd, Pi-hole, Portainer, Home Assistant).
Internal Link Tab:
- Purpose: This type of tab is for services that are part of Organizr itself or for creating custom internal pages. You generally won't use this for external services. It's more for developers or advanced customizations linking to Organizr's internal routes.
- For most users integrating external services, iFrame is preferred over this for displaying content within Organizr.
External Link Tab:
- Purpose: This tab type simply acts as a traditional hyperlink. When you click an External Link tab, it will open the specified URL in a new browser tab or window, outside of the Organizr interface.
- Pros: Works for any website, even those that block iFraming.
- Cons: It takes you out of the Organizr interface, so it's less integrated.
- Use Cases: Useful for websites that don't allow iFraming (e.g., Google, many banking sites, some news sites), or for links you prefer to open separately.
Other Tab Types: Organizr may offer other specialized tab types (e.g., for specific built-in Organizr features or plugins). For basic service integration, iFrame and External Link are your primary tools.

Adding a Service - Step-by-Step Guide:

Let's walk through the process of adding a new tab:

Log in to Organizr: Ensure you are logged in with your administrator account.
Navigate to the Tab Editor:
- In the top navigation bar of Organizr, click on the Settings icon (usually a cogwheel/gear).
- In the settings menu (often on the left sidebar), find and click on "Tabs" or "Tab Editor."
Create a New Tab:
- You'll see an interface for managing tabs. Click on the button to add a new tab (e.g., "Add Tab," "New Tab," or a "+" icon).
Configure Tab Details: A form will appear with several fields to configure your new tab. Here are the most important ones:
- Tab Name: This is the display name for the tab that will appear in Organizr's sidebar or tab list. Make it descriptive (e.g., "Sonarr," "Router Admin," "Tech News").
- Tab URL: This is the full web address (URL) of the service or website you want to add.
  - For local services, this will typically be like http://<service_ip_address>:<port> (e.g., http://192.168.1.50:8989 for Sonarr).
  - For external websites, it's the full HTTPS or HTTP URL (e.g., https://www.example.com).
- Tab Type: Select the appropriate type from the dropdown list.
  - Choose "iFrame" if you want to embed the service within Organizr.
  - Choose "External Link" if you want it to open in a new browser tab.
- Tab Local URL (Optional, for iFrame tabs): If you access Organizr both locally (e.g., http://192.168.1.100:8999) and externally (e.g., https://mydashboard.example.com via a reverse proxy), you might have different URLs for the same service.
  - The Tab URL would be the one accessible from outside your network (or the primary one).
  - The Tab Local URL would be the direct IP address and port accessible only from inside your network. Organizr can try to use the local URL if it detects you're accessing Organizr locally. For now, you can often leave this blank and just use the direct local IP in "Tab URL" if you're only accessing Organizr on your LAN.
- Tab Icon: You can choose an icon for your tab. Organizr often supports Font Awesome icons. You can type the name of an icon (e.g., fas fa-server, fab fa-youtube). There's usually a way to browse or search for icons. This adds a nice visual touch.
- Tab Category (Optional): If you plan to have many tabs, you can organize them into categories. You can create categories here or select existing ones.
- Enabled: Ensure this is checked for the tab to be active and visible.
- Ping (for iFrame tabs): If checked, Organizr will periodically try to reach the Tab URL to determine if the service is online. This can display a status indicator (green for online, red for offline) next to the tab.
- Is Protected (for iFrame tabs, more advanced): This relates to Organizr's SSO features. If a tab is marked as protected, Organizr might try to use its authentication mechanisms to secure access to it. We'll cover SSO later. For now, leave it unchecked unless you know what you're doing.
Save the Tab:
- Once you've filled in the necessary details, click the "Add" or "Save" button.
Test the New Tab:
- Your new tab should now appear in the tab list in Organizr's sidebar.
- Click on it to see if it works as expected.
  - If it's an iFrame tab, the service's interface should load within Organizr.
  - If it's an External Link tab, a new browser tab should open to the specified URL.

Potential Issue: X-Frame-Options and iFrames

If you try to iFrame a service and get a blank page, an error message within the iFrame, or a message in your browser's developer console (press F12 to open) like "Refused to display 'URL' in a frame because it set 'X-Frame-Options' to 'SAMEORIGIN' or 'DENY'", it means that service is configured to prevent itself from being embedded in iFrames on other domains (or at all).

Solutions:
- For services you control (self-hosted): You might be able to configure the service's web server (e.g., NGINX, Apache) to modify or remove the X-Frame-Options header, or to set a Content-Security-Policy frame-ancestors header that allows your Organizr domain. This is an advanced topic.
- For external websites or services you don't control: You usually can't change this. Your only option is to use an "External Link" tab type for these.
- Reverse Proxy: Sometimes, a reverse proxy setup can help mitigate some iFrame issues, especially those related to mixed content (HTTP in an HTTPS page) or by consistently serving all services under the same primary domain.

Start by adding a couple of your most frequently used services. This will give you a feel for the process and allow you to see your dashboard begin to take shape.

Workshop: Integrating Your First Two Services

Goal: To add two functional tabs to your new Organizr dashboard: one for a locally hosted service (using an iFrame tab) and one for an external website (using an External Link tab).

Prerequisites:

Organizr is installed, configured, and you are logged in as an administrator.
You have at least one other self-hosted service running on your local network with a web interface (e.g., your router's admin page, Pi-hole, Sonarr, Radarr, Portainer, etc.). Know its IP address and port.
You have a favorite external website you visit often (e.g., a news site, a forum).

Let's assume for this workshop:

Your Organizr is accessible at http://192.168.1.100:8088.
You have a service like Portainer running at http://192.168.1.100:9000 (or your router at http://192.168.1.1).
You want to add a link to a news site like https://news.ycombinator.com.

Part 1: Adding a Local Service as an iFrame Tab (e.g., Portainer)

Log in to Organizr: Ensure you are logged into your Organizr instance.
Navigate to Tab Editor:
- Click the Settings icon (cogwheel) in the top bar.
- In the left sidebar of the settings page, click on "Tabs" and then "Tab Editor".
Add a New Tab:
- Click the "+ Add Tab" button (or similar, like a "+" icon). A form for new tab details will appear.
Configure the "Portainer" Tab:
- Tab Name: Portainer
  - Explanation: This is the friendly name that will appear in your tab list.
- Tab URL: http://192.168.1.100:9000 (Replace with the actual URL of your Portainer instance or other local service. Make sure it's accessible directly in your browser first.)
  - Explanation: This is the address Organizr will try to load into the iFrame.
- Tab Type: Select "iFrame" from the dropdown.
  - Explanation: We want to embed Portainer's interface directly within Organizr.
- Tab Local URL: Leave this blank for now.
  - Explanation: We're assuming primary access from the local network. This field is for more complex setups with external access.
- Tab Icon:
  - Type fas fa-cubes or browse for an appropriate icon (Portainer often relates to containers/cubes). Many services have brand icons like fab fa-docker if it's Docker related.
  - Explanation: Icons make your dashboard visually appealing and easier to navigate.
- Tab Category: Leave blank or create a "Utilities" category if you like.
- Enabled: Ensure this is checked (it usually is by default).
- Ping: Check this box.
  - Explanation: Organizr will show a small green dot if Portainer is reachable, or red if not.
- Is Protected: Leave this unchecked.
Save the "Portainer" Tab:
- Click the "Add" or "Save" button at the bottom of the form.
Test the "Portainer" Tab:
- The "Portainer" tab should now appear in your tab list on the left (or top, depending on your Organizr theme/layout).
- Click on "Portainer".
- The Portainer login page or interface should load within the main content area of Organizr.
- Troubleshooting Note: If Portainer (or your chosen service) doesn't load and you see a blank page or an error, it might be due to X-Frame-Options. Open your browser's developer console (F12, then go to "Console") to check for errors. Some services, by default, prevent iFraming. Portainer usually allows it. If your chosen service blocks iFraming, you might need to choose a different local service for this part of the workshop or change its type to "External Link."

Part 2: Adding an External Website as an External Link Tab (e.g., Hacker News)

Navigate to Tab Editor (if you left it):
- If you're not already there, go back to Settings -> Tabs -> Tab Editor.
Add Another New Tab:
- Click the "+ Add Tab" button again.
Configure the "Hacker News" Tab:
- Tab Name: Hacker News
- Tab URL: https://news.ycombinator.com
- Tab Type: Select "External Link" from the dropdown.
  - Explanation: We want this to open in a new browser tab, as many external news sites might block iFraming or are better viewed full-screen.
- Tab Local URL: Leave this blank.
- Tab Icon: Type fas fa-newspaper or find a suitable icon.
- Tab Category: Leave blank or create a "News" or "Internet" category.
- Enabled: Ensure this is checked.
- Ping: You can leave this unchecked for external links, as their uptime isn'g't typically what you're monitoring with Organizr's ping.
- Is Protected: Leave this unchecked.
Save the "Hacker News" Tab:
- Click the "Add" or "Save" button.
Test the "Hacker News" Tab:
- The "Hacker News" tab should now appear in your tab list.
- Click on "Hacker News".
- A new browser tab (or window) should open, navigating to https://news.ycombinator.com. The Organizr interface itself should remain unchanged in its original tab.

You have now successfully added two different types of tabs to your Organizr dashboard! One integrates a local service directly into the UI, and the other provides a quick link to an external resource. You can repeat these steps to add more of your self-hosted services and favorite websites, gradually building out your personalized command center.

2. Intermediate Customization and Integration

Having mastered the basic setup and added your initial services, it's time to delve into Organizr's intermediate features. This section will focus on enhancing your dashboard's functionality, appearance, and user experience. We'll explore user management to control access, dive into theming for a personalized look, set up homepage items for at-a-glance information from your key services, and introduce the concept of reverse proxies, which are crucial for secure external access and cleaner URLs. These steps will transform your basic dashboard into a more powerful and tailored tool.

User Management and Permissions

As your Organizr dashboard becomes more central to your self-hosted ecosystem, you might want to share it with family members, friends, or collaborators. Organizr's user management system allows you to create multiple user accounts and control precisely what each user or group of users can see and do. This is essential for security, privacy, and providing a tailored experience for different people.

Key Concepts in Organizr User Management:

Users: These are individual accounts, each with a unique username and password. The account you created during the initial setup wizard is an administrator account.
Groups: Users can be assigned to one or more groups. Groups are a way to manage permissions collectively. Instead of assigning permissions to each user individually (which can become tedious), you assign permissions to a group, and all users in that group inherit those permissions.
Permissions: These are specific rights or restrictions that determine what a user or group can access or modify within Organizr. Examples include:
- Viewing specific tabs.
- Accessing Organizr settings (e.g., Tab Editor, User Management, Theming).
- Viewing or interacting with specific homepage items.
- Using SSO features.
Administrator Role: Typically, one or more users (and a default "Administrators" group) have full permissions to manage all aspects of Organizr.
Guest Access: Organizr can be configured to allow guest access, where users who are not logged in can see a limited, predefined set of tabs or information.

Creating New Users:

Navigate to User Management:
- Log in to Organizr as an administrator.
- Go to Settings (cogwheel icon).
- In the settings sidebar, click on "Users" and then "User Management" (or similar phrasing like "Manage Users").
Add a New User:
- You'll see a list of existing users (initially, just your admin account).
- Click on the button to add a new user (e.g., "+ Add User").
Fill in User Details:
- Username: A unique username for the new account.
- Password: A strong password for the user.
- Confirm Password: Re-enter the password.
- Email: The user's email address (optional but useful).
- Group Assignment: You'll likely see a list of available groups (e.g., "Administrators," "Users"). You can assign the new user to one or more existing groups. It's common to have a default "Users" group for standard, non-admin access.
- Other Options: There might be other options like setting an avatar, enabling/disabling the account, etc.
Save the User: Click "Add" or "Save."

Understanding and Managing User Groups:

Groups are the cornerstone of efficient permission management.

Default Groups: Organizr usually comes with a few default groups, such as:
- Administrators: Full control.
- Users: A standard group for regular users, often with view-only access to most things by default.
- Guest: Defines what non-logged-in users see (if guest access is enabled).
Creating New Groups:
- In the User Management section, there's usually a tab or subsection for "Group Management" or "Manage Groups."
- Click to add a new group.
- Group Name: Give the group a descriptive name (e.g., "Kids," "Power Users," "Family").
Assigning Permissions to Groups: This is the most critical part.
- After creating or selecting a group, you'll find an interface to configure its permissions. This interface can be quite detailed.
- Tab Access: You can specify which tabs are visible or hidden for this group. Often, this is a checklist of all your configured tabs.
- Settings Access: You can grant or deny access to various parts of Organizr's settings panel (e.g., prevent standard users from changing themes or managing other users).
- Homepage Item Access: Control which homepage items are visible.
- Other Permissions: Depending on Organizr's features and plugins, there might be more granular permissions (e.g., API access, ability to use certain tools).
- The "Deny" principle: It's often a good security practice to start with minimal permissions and explicitly grant what's needed, rather than granting everything and then trying to restrict.

Restricting Access Example:

Imagine you want to create a "Kids" group that can only see a tab for Jellyfin (a media server) and a tab for a kid-friendly website.

Create a new group named "Kids."
Edit the "Kids" group permissions.
In the "Tab Access" section, deselect all tabs by default (if that's an option, or manually uncheck them).
Then, specifically select (check) only the "Jellyfin" tab and the "Kid-Friendly Site" tab to be visible for this group.
Ensure all settings-related permissions are denied for the "Kids" group.
Create user accounts for your children and assign them to the "Kids" group.

Guest Access Configuration:

In Organizr's main settings (often under Main -> Login or a similar section), you can configure guest access.
You can enable or disable guest access entirely.
If enabled, you then configure the permissions for the "Guest" group (as described above) to define what non-logged-in visitors can see. This is useful if you want to share a very limited public view of your dashboard (e.g., just an Uptime Kuma status page).

Best Practices for User Management:

Principle of Least Privilege: Grant users and groups only the permissions they absolutely need to perform their intended tasks.
Use Strong Passwords: Enforce or encourage strong, unique passwords for all user accounts.
Regularly Review Permissions: Periodically check user accounts and group permissions, especially if your dashboard or user base changes.
Avoid Using the Admin Account for Daily Use: Once set up, consider creating a separate "standard user" account for yourself for daily browsing of your dashboard, and only log in as admin when you need to make configuration changes. This reduces the risk associated with being constantly logged in with full privileges.

Effective user management makes Organizr a more secure, versatile, and family-friendly dashboard solution, allowing you to tailor the experience for everyone who uses it.

Workshop: Creating User Roles for Family Members

Goal: To set up distinct user groups with different access levels in Organizr, suitable for a typical family scenario: an "Admin" (yourself), a "Standard User" (e.g., a spouse or partner), and a "Kid" user with very restricted access.

Prerequisites:

Organizr is installed, and you are logged in as the primary administrator.
You have at least 3-4 tabs already configured in Organizr. For this workshop, let's assume you have tabs like:
- Sonarr (media management)
- Router Admin (network settings)
- Plex (media server)
- KidsTube (a hypothetical kid-safe video site tab)
- Settings (this isn't a tab you create, but access to Organizr settings is a permission)

Scenario Users and Groups:

Your Admin Account: Already exists. Has full access. (Belongs to "Administrators" group).
Spouse User (e.g., username "partner"): Should be able to see Sonarr and Plex but not Router Admin or Organizr settings. Belongs to a new "Family Adults" group.
Child User (e.g., username "junior"): Should only see Plex and KidsTube. No access to anything else. Belongs to a new "Children" group.

Steps:

Log in as Administrator: Ensure you're logged into Organizr with your main admin account.
Navigate to Group Management:
- Click the Settings icon (cogwheel).
- In the settings sidebar, go to Users -> Group Management.
Create the "Family Adults" Group:
- Click "+ Add Group" (or similar button).
- Group Name: Family Adults
- Homepage (Default Tab): You can select a default tab for this group when they log in (e.g., Plex). This is optional.
- Click "Add".
- Now, find "Family Adults" in the group list and click on it (or an "Edit" icon next to it) to manage its permissions.
- Tab Visibility/Access:
  - You'll see a list of all your tabs.
  - Ensure Sonarr is checked (visible/allowed).
  - Ensure Plex is checked.
  - Ensure Router Admin is unchecked (hidden/denied).
  - Ensure KidsTube is unchecked (or checked, depending on preference for adults). Let's assume unchecked for this specific adult role to differentiate from kids.
- Permissions (Settings Access):
  - Scroll down to the permissions section. This section lists various administrative rights.
  - Crucially, uncheck permissions related to Organizr settings, such as:
    - Access Settings (or similar overall settings access)
    - Manage Users, Manage Groups
    - Tab Editor
    - Theme Settings, etc.
  - The goal is to give them access to use the dashboard and view allowed tabs, but not change its configuration.
- Click "Save" or "Update Group".
Create the "Children" Group:
- Back in Group Management, click "+ Add Group".
- Group Name: Children
- Homepage (Default Tab): Select Plex or KidsTube.
- Click "Add".
- Find "Children" in the group list and click to edit its permissions.
- Tab Visibility/Access:
  - Ensure Plex is checked.
  - Ensure KidsTube is checked.
  - Ensure Sonarr is unchecked.
  - Ensure Router Admin is unchecked.
- Permissions (Settings Access):
  - Uncheck ALL administrative permissions. Children should not have access to any settings.
- Click "Save" or "Update Group".
Navigate to User Management:
- In the settings sidebar, go to Users -> User Management.
Create the "partner" User:
- Click "+ Add User".
- Username: partner
- Password: Set a strong password (e.g., PartnerPass123!).
- Confirm Password: Re-enter the password.
- Email (Optional): partner@example.com
- Groups:
  - Uncheck "Users" (if it's checked by default).
  - Check the "Family Adults" group.
- Click "Add".
Create the "junior" User:
- Click "+ Add User".
- Username: junior
- Password: Set a strong password (e.g., JuniorPass789!).
- Confirm Password: Re-enter the password.
- Email (Optional):
- Groups:
  - Uncheck "Users" (if checked).
  - Check the "Children" group.
- Click "Add".
Test the New User Accounts and Permissions:
- Log out of your administrator account (click your user icon in the top right, then "Logout").
- Test "partner" user:
  - Log in with username partner and the password you set.
  - Verify that "partner" can see the Sonarr and Plex tabs.
  - Verify that "partner" cannot see the Router Admin or KidsTube tabs.
  - Verify that "partner" cannot access Organizr settings (the cogwheel icon might be hidden or lead to a restricted page).
  - Log out.
- Test "junior" user:
  - Log in with username junior and the password you set.
  - Verify that "junior" can see the Plex and KidsTube tabs.
  - Verify that "junior" cannot see Sonarr or Router Admin tabs.
  - Verify that "junior" cannot access Organizr settings.
  - Log out.
- Log back in as Administrator: Confirm you can still see everything and access all settings.

You have now successfully created different user roles with tailored access permissions. This demonstrates the power of Organizr's group-based permission system, allowing you to create a shared yet personalized dashboard experience for different users in your household.

Theming and Appearance Customization

One of the most enjoyable aspects of personalizing Organizr is customizing its appearance. A well-chosen theme and a few tweaks can make your dashboard not only more visually appealing but also more user-friendly and reflective of your personal style. Organizr offers a robust theming system, including built-in themes, a marketplace for community-created themes, and options for custom CSS overrides.

Exploring Built-in Themes:

Organizr typically comes with a selection of pre-installed themes that you can switch between easily.

Accessing Theme Settings:
- Log in to Organizr as an administrator.
- Go to Settings (cogwheel icon).
- In the settings sidebar, navigate to "Customize" (or "Appearance") and then "Theme."
Selecting a Theme:
- You'll see a dropdown list or a selection of cards representing the available built-in themes (e.g., "Default," "Dark," "Light," "Plex Inspired").
- Select a theme from the list. The appearance of your Organizr interface should update in real-time or after you click a "Preview" or "Apply" button.
- Experiment with the different built-in themes to see which ones you like.
Saving Your Choice:
- Once you've found a built-in theme you like, make sure to click "Save Settings" or "Apply" to make it permanent.

Using the Theme Marketplace:

The Organizr community is active, and many users create and share their own themes. These are often available through an integrated Theme Marketplace.

Accessing the Marketplace:
- In the theme settings (Settings -> Customize -> Theme), look for a tab or button labeled "Marketplace," "Browse Themes," or "Download Themes."
Browsing and Installing Themes:
- The marketplace will display a list of available themes, often with previews and descriptions.
- Browse through the themes. Common styles include Material Design, Plex-like themes, various dark/light themes, and themes inspired by other applications.
- When you find a theme you're interested in, there will usually be an "Install" or "Download" button. Clicking this will download the theme files to your Organizr instance.
Applying a Marketplace Theme:
- After installing a theme from the marketplace, it should appear in your list of available themes (back on the main theme selection page/tab).
- Select the newly installed theme and apply it just like a built-in theme.
- Remember to save your settings.

Basic CSS Overrides for Minor Tweaks:

Sometimes, you might like a theme overall but want to change a specific element – perhaps a font size, a color, or the spacing of an item. Organizr allows you to add custom CSS (Cascading Style Sheets) to override the theme's default styles.

Accessing Custom CSS Area:
- In the Organizr settings, look for a section like "Customize" -> "Custom CSS" or "Appearance" -> "Advanced CSS."
Adding CSS Rules:
- You'll find a text box where you can enter your CSS rules.
- To make effective CSS overrides, you'll need to know how to use your browser's developer tools (usually by pressing F12) to "Inspect" elements on the page. This allows you to see their existing CSS selectors (like IDs and classes) and styles.
- Example: Let's say you want to change the color of the main header text.
  - Right-click on the header text in Organizr and choose "Inspect" or "Inspect Element."
  - In the developer tools, find the HTML element for the header and look at its CSS classes or ID. Let's imagine it has a class .header-title.
  - In Organizr's Custom CSS box, you could add:
```
.header-title {
    color: #FF5733 !important; /* A nice orange color */
}
```
    The !important flag can sometimes be necessary to ensure your custom style overrides the theme's style, but use it judiciously as overuse can make CSS harder to manage.
Saving Custom CSS:
- After adding your CSS rules, click "Save Settings." Your changes should apply immediately or after a page refresh.
- Caution: Be careful with custom CSS. Incorrect rules can break the layout or appearance of your dashboard. Always make small changes and test. If something goes wrong, you can remove your custom CSS to revert.

Custom Logos and Favicons:

Personalizing your dashboard with your own logo and favicon (the small icon that appears in browser tabs) adds a professional and unique touch.

Accessing Image Upload Settings:
- In Organizr settings, look for a section like "Customize" -> "Images," "Appearance" -> "Branding," or similar.
Uploading a Custom Logo:
- There will typically be an option to upload a logo file (e.g., for the login page, the main header).
- Recommended formats: PNG (for transparency) or SVG (for scalability).
- Ensure your logo dimensions are appropriate for where it will be displayed. Too large, and it might look out of place; too small, and it might be pixelated.
- Follow the on-screen prompts to select and upload your logo image.
Uploading a Custom Favicon:
- Similarly, there should be an option to upload a favicon.
- Favicon format: .ico is the traditional format, but modern browsers also support .png (often 16x16, 32x32, or larger sizes).
- Upload your favicon file.
Saving Changes:
- Click "Save Settings." You might need to clear your browser cache or do a hard refresh (Ctrl+F5 or Cmd+Shift+R) to see the new favicon.

Tips for Theming:

Consistency: Try to choose a theme or customize colors that align with the services you use most or your personal preferences.
Readability: Ensure good contrast between text and background colors for readability.
Simplicity: Sometimes, less is more. A clean, uncluttered theme can be more effective than an overly complex one.
Performance: Very complex themes with many animations or large background images could slightly impact performance on less powerful client devices, though this is generally not a major issue with Organizr.

By exploring these theming and customization options, you can significantly enhance the visual appeal and user experience of your Organizr dashboard, making it truly your own.

Workshop: Personalizing Your Organizr Look and Feel

Goal: To apply a new theme to your Organizr instance from the marketplace and then customize the login page logo and add a small custom CSS tweak.

Prerequisites:

Organizr is installed, and you are logged in as an administrator.
You have a custom logo image file ready (e.g., a .png or .jpg file). If you don't have one, you can find a generic one online for practice or create a simple one. For this workshop, a small, roughly square or wide rectangular logo is fine. Let's say you have mylogo.png.
Basic familiarity with navigating Organizr settings.

Steps:

Log in as Administrator: Ensure you are logged into Organizr.
Explore and Install a Theme from the Marketplace:
- Navigate to Settings (cogwheel icon).
- In the settings sidebar, go to Customize -> Theme.
- Click on the "Marketplace" tab (or similar wording like "Browse Online").
- You'll see a list of themes available for download. Look for a theme that appeals to you. For this workshop, let's try to find and install a popular one like "Material Design" or "Plex Theme" (if available and you like Plex's aesthetic). If those specific names aren't there, choose another well-rated or visually distinct theme.
- Click the "Install" or "Download" button next to your chosen theme. Wait for it to complete.
- Once installed, go back to the "Theme" tab (where you select your active theme).
- Your newly installed theme should now appear in the dropdown list or selection area. Select it.
- The Organizr interface should update to reflect the new theme.
- Click "Save Settings" at the bottom of the page.
Upload a Custom Login Page Logo:
- In the Organizr settings sidebar, navigate to Customize -> Images (or it might be under "Login Page" or "Branding" depending on the Organizr version and theme structure).
- Look for an option specifically for the "Login Logo" or "Login Page Image."
- Click the "Upload" or "Choose File" button associated with the login logo.
- Browse your computer and select your mylogo.png file (or whatever logo you prepared).
- After uploading, you might see a preview.
- Click "Save Settings".
- Test it: Log out of Organizr. You should see your new logo on the login page. Log back in.
(Optional) Upload a Custom Header Logo/Favicon (if separate options exist):
- If your theme or Organizr version has separate options for a "Header Logo" (the logo seen when you're logged in) or a "Favicon" (the small icon in the browser tab), you can upload your logo or a suitable favicon image there as well. Follow the same process as for the login logo.
- Remember to "Save Settings" after each change.
- To see favicon changes, you might need to do a hard refresh of your browser (Ctrl+F5 or Cmd+Shift+R) or clear its cache.
Add a Small Custom CSS Change (Example: Modify Login Button Color):
- Navigate to Settings -> Customize -> Custom CSS.
- We'll try to change the background color of the login button on the login page. First, we need to find its CSS selector.
- Open a new private/incognito browser window and go to your Organizr login page. This way, you can inspect elements without being logged in.
- Right-click on the Login button and choose "Inspect" or "Inspect Element".
- In the developer tools, carefully examine the HTML for the button and its CSS classes. Look for a prominent class associated with the button. For example, it might be something like .login-button, #btnLogin, or a class provided by the theme like .theme-login-button. Note this selector. (Let's assume for this workshop it's .btn-login, but it WILL vary by theme).
- Now, back in your logged-in Organizr window with the Custom CSS box open, add the following CSS rule. Replace .btn-login with the actual selector you found.
```
/* Custom CSS to change login button color */
.btn-login { /* Replace .btn-login with the actual class/ID you found! */
    background-color: #4CAF50 !important; /* A green color */
    color: white !important; /* Ensure text is readable */
}
```
  - Explanation:
    - .btn-login is the selector targeting the login button.
    - background-color: #4CAF50 !important; changes its background to green.
    - color: white !important; changes its text color to white.
    - !important is used here to increase the specificity of our rule, making it more likely to override the theme's default styles. Use it sparingly.
- Click "Save Settings" in the Custom CSS section.
- Test it: Log out of Organizr (or refresh the login page in your private window). The login button should now have your custom color. If not, double-check your CSS selector and ensure there are no typos. CSS is case-sensitive.

You have now successfully applied a new theme, personalized it with a custom logo, and even made a minor style adjustment using custom CSS. Your Organizr dashboard should now have a look and feel that is more uniquely yours! Feel free to experiment further with other themes or CSS tweaks as you get more comfortable.

Setting Up Homepage Items

While tabs provide access to the full interfaces of your services, Homepage Items in Organizr offer a way to display key information, summaries, or quick actions directly on your Organizr landing page (the "Homepage"). This gives you an at-a-glance overview of your important services without needing to click into each tab. Organizr supports a variety of built-in homepage items for popular self-hosted applications.

Difference Between Tabs and Homepage Items:

Tabs:
- Typically iFrame the entire web UI of a service.
- Provide full access to the service's functionality within Organizr.
- Located in the sidebar or top bar for navigation.
Homepage Items:
- Widgets displayed on the Organizr homepage.
- Show specific, curated information (e.g., download queue, upcoming media, server stats).
- Often rely on API communication with the target service.
- Provide quick insights and sometimes quick actions.

Available Homepage Item Types (Examples):

Organizr has built-in support for many popular services, often from the "Arr" suite and download clients. Common examples include:

Sonarr: Upcoming TV shows, calendar, missing episodes.
Radarr: Upcoming movies, recently added, missing movies.
Lidarr: For music (similar functionality to Sonarr/Radarr but for music).
Readarr: For books/magazines/audiobooks.
NZBGet/SABnzbd: Download speed, queue status, history.
Plex/Emby/Jellyfin: Recently added media, currently playing.
Tautulli/Petio: Plex statistics, user activity.
Pi-hole/AdGuard Home: DNS query stats, blocking status.
Uptime Kuma/Healthchecks.io: Status of monitored services.
Transmission/qBittorrent: Torrent status.
Weather: Current weather conditions for a specified location.
System Information: Basic server stats (CPU, RAM, Disk).
Custom HTML: Allows you to embed your own HTML code as a homepage item.

Configuring Homepage Items - General Steps:

The exact configuration will vary slightly for each item type, but the general process is similar:

Navigate to Homepage Item Settings:
- Log in to Organizr as an administrator.
- Go to Settings (cogwheel icon).
- In the settings sidebar, find "Homepage" or "Homepage Items" and click on it. You might see sub-options like "Manage Items" or "Add Item."
Add a New Item:
- Click the button to add a new homepage item (e.g., "+ Add Item," "New Homepage Item").
Select Item Type:
- A dropdown list or a selection of cards will appear, showing all available homepage item types (Sonarr, Radarr, Weather, etc.).
- Choose the type of item you want to add.
Configure Item-Specific Settings: This is where you provide the details Organizr needs to connect to the service and retrieve information. Common fields include:
- Item Name: A display name for this item on your homepage (e.g., "Upcoming TV," "Movie Queue").
- Service URL: The full URL to access the service (e.g., http://192.168.1.50:8989 for Sonarr). This should be the address Organizr can reach.
- API Key: Most services require an API key for Organizr to access their data. You'll need to find this API key within the settings of the target service itself (e.g., in Sonarr's Settings -> General section).
- Username/Password (Less Common for API items): Some older or different integrations might use username/password instead of or in addition to an API key.
- Display Options: Many items offer customization for what information is shown and how it's presented (e.g., number of items to display, sort order, show/hide specific details).
- Refresh Interval: How often Organizr should fetch new data for this item.
- Enabled: Make sure it's checked to activate the item.
Save the Item:
- Click "Add," "Save," or "Update Item."
Arrange Items on Homepage (Optional):
- Once you have multiple homepage items, Organizr usually provides a way to drag and drop them to rearrange their order and layout on the homepage. This might be on the same "Manage Items" page or a separate "Layout" page.
Check Your Homepage:
- Navigate back to your main Organizr homepage (usually by clicking the Organizr logo or a "Home" button).
- You should see your newly configured homepage item displaying information from the service.

Important Considerations:

API Keys: Treat API keys like passwords. They grant access to your services.
Network Accessibility: Organizr (running on your server) must be able to reach the Service URL you provide for the homepage item. If Sonarr is running in another Docker container, ensure they are on the same Docker network or that Sonarr's port is correctly exposed and reachable by Organizr's container.
Service Configuration: Ensure the service itself is configured to allow API access and that its API is enabled.
Troubleshooting: If an item doesn't display data:
- Double-check the URL and API key for typos.
- Verify network connectivity between Organizr and the service.
- Check Organizr's logs (Settings -> System -> View Log) for any error messages related to homepage items.
- Check the service's logs for any denied API requests.

Homepage items significantly enhance the "dashboard" aspect of Organizr, providing valuable, consolidated information right where you need it.

Workshop: Integrating Sonarr/Radarr on Your Homepage

Goal: To add a homepage item to your Organizr dashboard that displays information from an existing Sonarr (or Radarr) instance, such as upcoming TV shows or recently added movies.

Prerequisites:

Organizr is installed, and you are logged in as an administrator.
You have a functional Sonarr (for TV shows) or Radarr (for movies) instance running and accessible on your network.
- If you don't have Sonarr/Radarr, you can adapt this workshop for another supported service like NZBGet, SABnzbd, or Plex, but the specific fields (like API key location) will differ. We'll proceed with Sonarr as the primary example.
You know the URL for your Sonarr/Radarr instance (e.g., http://192.168.1.50:8989).
You know how to find the API key for your Sonarr/Radarr instance.

Finding the API Key in Sonarr (Radarr is very similar):

Open your Sonarr web interface.
Navigate to Settings (usually a cogwheel or wrench icon on the left sidebar).
Go to the General tab/section.
Look for the "API Key" field. It's a long string of letters and numbers.
Copy this API key. You'll need it in Organizr.

Steps to Add the Sonarr Homepage Item in Organizr:

Log in to Organizr: Use your administrator account.
Navigate to Homepage Item Settings:
- Click the Settings icon (cogwheel) in Organizr's top bar.
- In the settings sidebar, click on Homepage -> Homepage Items (or it might be just "Homepage" and then you'll see options for items).
Add a New Homepage Item:
- Click the "+ Add Item" button (or similar).
Select "Sonarr" as the Item Type:
- From the dropdown list or selection of item types, choose "Sonarr".
- (If you're doing Radarr, choose "Radarr". The fields will be almost identical).
Configure the Sonarr Homepage Item: A form will appear for Sonarr-specific settings. Fill it out as follows:
- Enable Item: Make sure this checkbox is checked.
- Item Name: Give it a descriptive name.
  - Example: Upcoming TV Shows or Sonarr Overview
- Sonarr URL: Enter the full URL of your Sonarr instance.
  - Example: http://192.168.1.50:8989 (use http or https as appropriate for your Sonarr setup).
  - Important: Do not add a trailing slash / unless your Sonarr specifically requires it for API access (most don't).
- Sonarr API Key: Paste the API key you copied from Sonarr's settings here.
  - Example: abcdef1234567890abcdef1234567890
- Item Type/Data to Display (Sonarr specific options): Sonarr items often let you choose what to display. You might see options like:
  - Calendar: Shows upcoming episodes in a calendar view.
  - Upcoming: A list of upcoming episodes.
  - Recently Aired: Episodes that recently aired.
  - Missing: Shows missing episodes.
  - Select "Upcoming" or "Calendar" for a good visual overview.
- Number of Items (if applicable): If you chose "Upcoming," you might be able to specify how many upcoming episodes to show (e.g., 5, 10).
- Refresh Interval: How often Organizr should fetch data from Sonarr (e.g., "Every 5 minutes," "Every 15 minutes"). A moderate interval is usually fine.
- Advanced Options (Optional): There might be other toggles like "Open links in new tab." Configure as desired.
Save the Homepage Item:
- Click the "Add" or "Save Item" button at the bottom of the form.
Check Your Organizr Homepage:
- Navigate back to your main Organizr homepage (usually by clicking the Organizr logo or a "Home" icon).
- You should now see your new "Upcoming TV Shows" (or similar) item displayed. It might take a moment to load the data for the first time.
- If it's working, you'll see information pulled directly from your Sonarr instance.
(Optional) Rearrange Homepage Items:
- If you add more homepage items, go back to Settings -> Homepage -> Homepage Items. There's often a way to drag and drop the items in the list to change their display order on your homepage. Some Organizr versions might have a separate "Layout" section for this.

Troubleshooting:

No Data Displayed:
- Double-check URL and API Key: Typos are common. Ensure the URL is exactly how you access Sonarr (including http or https and port) and the API key is correct.
- Network Connectivity: Can the server running Organizr reach the Sonarr URL? If they are in different Docker containers, are they on the same Docker network, or is Sonarr's port correctly exposed? Try ping <sonarr_ip> or curl <sonarr_url> from the Docker host terminal to test basic connectivity. If Organizr itself is in a Docker container, it needs to be able to resolve and reach the Sonarr container/IP. Using container names (e.g., http://sonarr:8989) often works if they are on the same custom Docker network.
- Sonarr's API: Is Sonarr running correctly? Is its API accessible?
- Organizr Logs: Check Organizr's logs for errors (Settings -> System -> View Log or via docker logs <organizr_container_name>).
"API Key Invalid" Error (or similar): The API key is incorrect, or Sonarr is not recognizing it. Re-copy and paste.

By successfully adding this homepage item, you've made your Organizr dashboard more dynamic and informative, giving you quick access to important data from your media management tools. You can repeat this process for Radarr, Lidarr, download clients, and other supported services to build a comprehensive overview.

Introduction to Reverse Proxies with Organizr

As you expand your self-hosted services and begin using Organizr as your central dashboard, you'll likely want to access it more conveniently and securely, perhaps even from outside your home network. This is where a reverse proxy comes into play. While Organizr itself uses NGINX internally, placing it behind a dedicated reverse proxy offers significant advantages.

What is a Reverse Proxy?

A standard (or forward) proxy is something your computer uses to access the internet (e.g., in a corporate network). A reverse proxy, on the other hand, is a server that sits in front of one or more web servers (like your Organizr instance, Sonarr, Radarr, etc.). It intercepts requests from clients (like your web browser) and forwards them to the appropriate backend service.

Diagram:

Without Reverse Proxy (Local Access): Your Browser --- (LAN) ---> Server_IP:Organizr_Port (e.g., 192.168.1.100:8999) Your Browser --- (LAN) ---> Server_IP:Sonarr_Port (e.g., 192.168.1.100:8989)
With Reverse Proxy (Local or External Access): Your Browser --- (Internet/LAN) ---> yourdomain.com ---> Reverse Proxy --- (LAN) ---> Organizr Container (e.g., organizr:80) Your Browser --- (Internet/LAN) ---> sonarr.yourdomain.com ---> Reverse Proxy --- (LAN) ---> Sonarr Container (e.g., sonarr:8989)

Why Use a Reverse Proxy with Organizr (and other self-hosted services)?

Single Access Point & Clean URLs:
- Instead of remembering IP_Address:Port for every service, you can access them via subdomains (e.g., organizr.yourdomain.com, sonarr.yourdomain.com) or subpaths (e.g., yourdomain.com/organizr, yourdomain.com/sonarr). This is much cleaner and easier to remember.
- All traffic comes through the reverse proxy on standard web ports (usually port 80 for HTTP and 443 for HTTPS).
SSL/TLS Termination (HTTPS):
- This is a major security benefit. A reverse proxy can handle SSL/TLS encryption for all your services. You can install an SSL certificate (e.g., from Let's Encrypt, which offers free certificates) on the reverse proxy.
- Your browser connects to the reverse proxy via HTTPS (encrypted).
- The reverse proxy then communicates with your backend services (like Organizr) over HTTP on your local network (which is generally considered safe behind your firewall).
- This encrypts your data in transit, protecting usernames, passwords, and other sensitive information from eavesdropping, especially when accessing services from outside your home network.
- It also gives you the "padlock" icon in your browser, building trust and avoiding "Not Secure" warnings.
Load Balancing (More Advanced):
- If you had multiple instances of a service for high availability, a reverse proxy could distribute traffic among them. This is generally not needed for typical home Organizr setups but is a core capability.
Centralized Authentication and Access Control (More Advanced):
- Some reverse proxies can integrate with authentication systems (like Authelia, or even Organizr's own SSO via auth_request with NGINX) to protect services that don't have their own robust authentication.
Path-Based Routing / Subdomain Routing:
- As shown in the diagram, you can route traffic based on the requested hostname (subdomain) or URL path to different backend services.
Improved Security Headers:
- You can configure the reverse proxy to add important HTTP security headers (like HSTS, CSP, X-Frame-Options, X-Content-Type-Options) for all your services centrally, enhancing their security posture.
Hiding Backend Server Information:
- The reverse proxy acts as an intermediary, so the direct IP addresses and ports of your internal services are not exposed to the internet.

Popular Reverse Proxy Software (often run in Docker):

NGINX Proxy Manager (NPM):
- Very user-friendly, with a web UI for managing proxy hosts and SSL certificates (Let's Encrypt is built-in).
- Excellent choice for beginners and many intermediate users due to its simplicity.
- Based on NGINX.
Traefik:
- Powerful and dynamic, with excellent Docker integration (can automatically detect and configure routes for new containers).
- Steeper learning curve than NPM, configured mainly via YAML files or Docker labels.
- Also has built-in Let's Encrypt support.
Caddy:
- Known for its simplicity and automatic HTTPS by default (manages Let's Encrypt certificates automatically with minimal configuration).
- Configuration is done via a "Caddyfile."
HAProxy:
- Very powerful, high-performance proxy, often used for load balancing in large-scale environments, but can also be used for home setups.
NGINX (Manually Configured):
- You can use NGINX directly and write the configuration files yourself. This offers maximum flexibility but requires more NGINX knowledge. Organizr itself runs on NGINX, but this would be a separate NGINX instance acting as the main public-facing proxy.

How Organizr Works Behind a Reverse Proxy:

When Organizr is behind a reverse proxy:

Your browser requests https://organizr.yourdomain.com.
DNS resolves organizr.yourdomain.com to your public IP address (where your reverse proxy is listening).
The request hits your reverse proxy on port 443 (HTTPS).
The reverse proxy terminates SSL (decrypts the request).
It then forwards the request (now typically over HTTP) to the internal IP and port where your Organizr Docker container is listening (e.g., http://192.168.1.100:8999 or http://organizr_container_name:80 if on the same Docker network).
Organizr processes the request and sends the response back to the reverse proxy.
The reverse proxy encrypts the response and sends it back to your browser via HTTPS.

Importance of X-Forwarded-For and X-Forwarded-Proto Headers:

When a reverse proxy forwards a request, the backend service (like Organizr) only sees the IP address of the reverse proxy, not the original client. To solve this, reverse proxies add headers:

X-Forwarded-For: Contains the original client's IP address.
X-Forwarded-Proto: Contains the original protocol used by the client (e.g., https or http).
X-Forwarded-Host: Contains the original host requested by the client.

Organizr (and its internal NGINX) needs to be configured to trust and use these headers, especially if you're using features like fail2ban or want accurate logging of client IPs. Most reverse proxy setups handle these headers correctly by default.

Setting up a reverse proxy is a highly recommended step for anyone serious about self-hosting, especially if planning external access. It significantly boosts security and convenience.

Workshop: Preparing for a Reverse Proxy (Conceptual)

Goal: To understand the benefits, components, and basic planning steps involved in setting up a reverse proxy for your Organizr instance and other self-hosted services. This workshop is conceptual and involves research rather than direct server configuration.

Prerequisites:

Your Organizr instance is running and accessible on your local network (e.g., http://192.168.1.100:8999).
You have an idea of other services you might want to access via the reverse proxy (e.g., Sonarr, Radarr).

Steps:

Diagram Your Current Access Method:

On a piece of paper or using a simple drawing tool, sketch how you currently access Organizr and one or two other self-hosted services.

Example:

Your PC/Laptop (Browser) --LAN--> Router --LAN--> Server (192.168.1.100)
                                                    |--> Organizr (port 8999)
                                                    |--> Sonarr (port 8989)
                                                    |--> Radarr (port 7878)

Label the IP addresses and port numbers you use.
Self-reflection: What are the inconveniences of this setup? (e.g., remembering IPs/ports, no HTTPS, difficult external access).

Diagram Your Desired Future Access Method (with a Reverse Proxy):

Now, sketch how you want to access these services. Imagine you have a domain name like myhome.example.com.

Example:

Your PC/Laptop (Browser) --Internet/LAN--> your_domain_name (e.g., myhome.example.com)
                               |
                               v
                         Your Router (Port Forwarding 80/443)
                               |
                               v
                 Server (192.168.1.100) running Reverse Proxy (on ports 80/443)
                       |       |       |
                       |       |       v (proxies to sonarr.myhome.example.com)
                       |       v (proxies to radarr.myhome.example.com)      Sonarr (internally on port 8989)
                       v (proxies to organizr.myhome.example.com)            Radarr (internally on port 7878)
                               Organizr (internally on port 8999)

Notice how all external access points to standard ports (80/443) on the reverse proxy, which then routes traffic internally. The URLs would be like https://organizr.myhome.example.com.

Research Domain Name Options and Dynamic DNS (DDNS):
- Domain Name: To use nice URLs like organizr.myhome.example.com, you need a domain name.
  - Paid Domains: You can purchase a domain from registrars like Namecheap, Google Domains, Cloudflare Registrar, GoDaddy, etc. (e.g., yourlastname.com, mycoolserver.net). This gives you full control.
  - Free Subdomains from DDNS Providers: Many Dynamic DNS services offer free subdomains (e.g., yourchoice.duckdns.org, yourchoice.no-ip.com).
- Dynamic DNS (DDNS): Most home internet connections have a dynamic public IP address, meaning it can change. A DDNS service runs a small client on your server (or sometimes on your router) that regularly updates the DDNS provider with your current public IP. The DDNS provider then ensures your chosen hostname (e.g., yourchoice.duckdns.org) always points to your current home IP.
  - Research:
    - Visit DuckDNS (duckdns.org) and No-IP (noip.com). Understand how they work.
    - Check if your router has built-in DDNS client support for any services.
    - If you choose a paid domain, you'll still likely need DDNS if your home IP is dynamic. Your domain registrar might offer DDNS, or you can use a third-party DDNS service and point a CNAME record from your paid domain to your DDNS hostname.
Identify Key Advantages of the Reverse Proxy Setup for Your Use Case:
- Based on the information in the "Introduction to Reverse Proxies" section and your research, list at least 3-5 specific advantages this new setup would bring to your self-hosting experience.
- Example List:
  1. "Secure access to Organizr with HTTPS from anywhere."
  2. "No more typing IP addresses and port numbers; just organizr.myhome.example.com."
  3. "A single SSL certificate for all my services, managed by the reverse proxy."
  4. "My family can access Plex via plex.myhome.example.com without needing to know the server IP."
  5. "Increased security by not exposing individual service ports directly to the internet."
Identify Key Components and Steps Needed:
- List the main software and configuration steps you anticipate needing for this setup.
- Example List:
  1. Choose and set up a domain/DDNS: (e.g., Get a DuckDNS subdomain).
  2. Choose a reverse proxy software: (e.g., NGINX Proxy Manager, Traefik, Caddy).
  3. Install the reverse proxy software: (Likely via Docker).
  4. Configure port forwarding on my router: Forward external ports 80 and 443 to the internal IP address of the server running the reverse proxy.
  5. Configure the reverse proxy:
    - Add proxy host entries for Organizr (e.g., organizr.myhome.example.com pointing to http://<local_organizr_ip>:<organizr_port>).
    - Enable SSL (Let's Encrypt) for these hosts.
    - Repeat for other services (Sonarr, Radarr, etc.).
  6. (Optional but recommended) Secure the reverse proxy management interface itself.

This conceptual workshop helps you internalize why a reverse proxy is beneficial and what's involved at a high level. The next step, covered in the "Advanced" section, would be the actual implementation of a reverse proxy like NGINX Proxy Manager. By doing this planning now, you'll be much better prepared for that practical implementation.

3. Advanced Features and Security

With a solid, customized Organizr dashboard in place and an understanding of reverse proxies, we now move into advanced configurations. This section focuses on leveraging Organizr's more powerful capabilities and significantly bolstering the security of your setup. We'll explore implementing Single Sign-On (SSO) to streamline authentication, provide a detailed guide on securing Organizr with a reverse proxy and SSL certificates, touch upon advanced NGINX configurations within Organizr itself, discuss robust backup and disaster recovery strategies, and finally, cover troubleshooting common issues. These advanced topics will elevate your Organizr deployment to a professional and resilient standard.

Implementing Single Sign-On (SSO)

Single Sign-On (SSO) is a powerful authentication scheme that allows users to log in with a single set of credentials to gain access to multiple independent software systems. In the context of Organizr and your self-hosted services, SSO can dramatically simplify the user experience by reducing the number of times users need to enter usernames and passwords. Organizr can act as an SSO provider itself or integrate with external authentication sources.

Concept of SSO and Its Benefits with Organizr:

User Convenience: The primary benefit is convenience. Users log in once (e.g., to Organizr) and are then automatically logged into other protected applications or have their access rights recognized without needing to re-authenticate for each service.
Centralized User Management: When Organizr acts as the SSO provider, user accounts and access policies can be managed in one place.
Improved Security (Potentially):
- Reduces password fatigue, as users only need to remember one strong password.
- Can make it easier to enforce consistent security policies (like two-factor authentication, if supported by the SSO provider) across multiple services.
- However, it also means that if the SSO provider is compromised, access to multiple services could be at risk. Therefore, securing the SSO provider itself is paramount.

Organizr as an SSO Provider:

Organizr has several ways it can participate in an SSO flow:

Organizr's Built-in Authentication:
- Organizr maintains its own user database (usernames, passwords, group memberships).
- This can be used as the primary authentication source.
External Authentication Backend Integration (Plex, Emby, Jellyfin, LDAP, OAuth):
- Organizr can be configured to delegate its own login process to an external service.
- Plex/Emby/Jellyfin SSO: Users can log into Organizr using their Plex, Emby, or Jellyfin credentials. This is very popular if these media servers are central to your setup. Organizr validates the credentials against the chosen media server.
- LDAP/Active Directory: For more complex environments, Organizr can authenticate against an LDAP server.
- OAuth 2.0 / OpenID Connect (OIDC): Organizr can act as an OAuth 2.0 client, allowing users to log in via external OAuth providers like Google, GitHub, Authelia, Keycloak, etc. (This is for logging into Organizr).
Organizr Protecting Other Applications (acting as an auth_request endpoint):
- This is a more advanced use of Organizr as an SSO provider.
- Requires a reverse proxy (like NGINX, Traefik) that supports an "authentication request" or "forward authentication" mechanism.
- How it works:
  1. User tries to access a protected application (e.g., sonarr.yourdomain.com).
  2. The reverse proxy intercepts the request and, before granting access to Sonarr, sends an authentication request to Organizr (e.g., to a special Organizr endpoint like /api/v2/auth&group=kodi).
  3. Organizr checks if the user has an active, valid session and if they belong to the required group (e.g., "kodi" group in Organizr).
  4. If authenticated and authorized, Organizr returns a 200 OK status to the reverse proxy, which then allows the user to access Sonarr.
  5. If not authenticated/authorized, Organizr returns a 401 Unauthorized status, and the reverse proxy can redirect the user to Organizr's login page. Once logged into Organizr, subsequent attempts to access Sonarr would succeed.
- This effectively uses Organizr's login and user/group management to protect other applications that might have weak or no authentication, or to provide a unified login experience.

Configuring Organizr's Built-in SSO (Plex Example):

Let's focus on a common scenario: using Plex credentials to log into Organizr.

Prerequisites:
- A running Plex Media Server instance.
- Organizr installed and accessible.
In Organizr:
- Log in as an administrator.
- Go to Settings -> Main -> SSO (or a similarly named section under "Main Settings" or "System Settings").
- Enable Plex Authentication: Find the option for Plex and enable it.
- Plex Server URL: Enter the full URL of your Plex server (e.g., http://192.168.1.10:32400 or https://plex.yourdomain.com if it's behind a reverse proxy).
- Plex Token (Optional but Recommended for specific scenarios): For some Plex SSO interactions, especially if Organizr needs to perform actions on behalf of the user or verify server ownership more strictly, a Plex Admin Token might be required. You can get this from Plex by inspecting network requests or using tools. Often, for basic login, just the URL is enough for Organizr to redirect to Plex for login.
- Plex Admin Username/Email & Password (Optional): Sometimes required for Organizr to initially connect or verify the Plex server.
- Allow New User Registrations via Plex: Decide if users who successfully authenticate via Plex but don't yet have an Organizr account should have one automatically created. If so, you can specify a default group for these new users.
- Login Type / Primary SSO Provider: Ensure Plex is selected as a primary or active SSO method for logging into Organizr itself.
Save Settings.
Test: Log out of Organizr. The login page should now offer an option like "Login with Plex." Clicking it should redirect you to Plex's login page (or use an existing Plex session). After successful Plex authentication, you should be redirected back to Organizr and logged in.

Configuring Organizr to Protect Other Apps (High-Level auth_request concept):

This is significantly more complex and involves configuring your reverse proxy.

In Organizr:
- Ensure users who should access the protected app are in a specific Organizr group (e.g., a group named "sonarr-users").
- Note the Organizr API endpoint for authentication checks. This is often like /api/v2/auth&group=ID where ID is the group ID or /auth-N where N is the auth level from Organizr's auth backend settings. Consult Organizr's documentation for the precise endpoint and parameters.
In your Reverse Proxy (e.g., NGINX, NGINX Proxy Manager, Traefik with ForwardAuth):
- For the service you want to protect (e.g., sonarr.yourdomain.com):
  - Configure an auth_request directive (NGINX) or forward authentication middleware (Traefik).
  - This directive points to the Organizr auth endpoint.
  - Specify what to do upon successful authentication (allow request to proceed to Sonarr) and failed authentication (redirect to Organizr's login page, often by setting a variable like $organizr_login_url = 'https://organizr.yourdomain.com'; and then using it in an error_page 401 = @error401; location @error401 { return 302 $organizr_login_url; }).
- This requires careful NGINX/Traefik configuration. NGINX Proxy Manager allows adding custom NGINX directives, which is where you'd place auth_request snippets.

Considerations for SSO:

Security of the SSO Provider: If Organizr (or Plex, etc.) is your SSO provider, it becomes a critical piece of infrastructure. Secure it well (strong passwords, 2FA if available, keep it updated).
Complexity: Full auth_request SSO is powerful but adds complexity to your reverse proxy configuration. Start with simpler SSO (like Plex login to Organizr) first.
Application Compatibility: Not all applications work seamlessly with all forms of SSO. iFramed applications within Organizr might still require their own login if they don't support header-based authentication or if the auth_request flow isn't passing credentials in a way they understand.
User Experience: While SSO aims to simplify, a poorly configured SSO can be frustrating. Test thoroughly.

SSO can be a game-changer for usability. Start by exploring Organizr's built-in options for authenticating to Organizr itself (like Plex SSO), and then, if your needs grow, you can investigate using Organizr to protect other applications via auth_request with your reverse proxy.

Goal: To configure Organizr to allow users to log in using their Plex credentials, simplifying the login process if Plex is a central service for your users.

Prerequisites:

Organizr is installed, and you are logged in as an administrator.
You have a running Plex Media Server instance, accessible from the server where Organizr is running.
You know the URL of your Plex Media Server (e.g., http://192.168.1.10:32400 or https://plex.yourdomain.com).
You (and any other test users) have valid Plex accounts that can access your Plex server.

Steps:

Log in to Organizr as Administrator:
- Access your Organizr instance and log in with your admin credentials.
Navigate to SSO Settings in Organizr:
- Click the Settings icon (cogwheel) in the top bar.
- In the settings sidebar, navigate to Main -> SSO (or it might be under "System," "Authentication," or a similar top-level category, then "SSO"). Look for the section that deals with different authentication backends.
Configure Plex Authentication Backend:
- You should see a list of available authentication backends (e.g., Local, Plex, Emby, Jellyfin, LDAP, OAuth).
- Locate the "Plex" section.
- Enable Plex: Check the box to enable Plex authentication.
- Plex Server URL:
  - Enter the full URL of your Plex Media Server.
  - Example: http://192.168.1.10:32400 or https://plex.mydomain.com (if Plex is behind its own reverse proxy with SSL).
  - Important: Ensure this URL is reachable from the Organizr container/server.
- Plex Admin Username / Email (Optional but sometimes helpful for initial setup):
  - You might see fields for Plex Admin Username/Email and Password. If present, you can fill these with your Plex admin credentials. This can sometimes help Organizr verify the connection to the Plex server. For basic user login, it's often not strictly needed as the user will authenticate directly with Plex.
- Plex Token (Usually not needed for basic login to Organizr):
  - Leave this blank for now unless Organizr specifically requires it for your version or intended use. A token is more for Organizr making API calls to Plex, not just for user login.
- Allow New User Registrations via Plex:
  - Decide if you want users who successfully authenticate via Plex (but don't yet have an account in Organizr) to have an Organizr account automatically created.
  - If you enable this (check the box), you'll typically need to select a "Default Group for Plex Users" (e.g., "Users," or a custom group you created). New users logging in via Plex will be added to this group.
  - For this workshop, enable this option and select your standard "Users" group or the "Family Adults" group if you created it in a previous workshop.
- Other Plex-specific options: Review any other settings like "Plex Timeout." Defaults are usually fine.
Set Plex as a Login Method for Organizr:
- Still within the SSO settings, or possibly in a section like Settings -> Main -> Login Settings, you need to ensure that "Plex" is an active method for users to log into Organizr.
- There might be a list of "Enabled Login Backends" or a "Primary SSO Provider" setting. Ensure Plex is selected or enabled here.
- Some Organizr versions might automatically enable it on the login page if the Plex backend is configured and enabled.
Save SSO Settings:
- Click the "Save Settings" button.
Test Plex SSO Login:
- Log out of your Organizr administrator account.
- You should now see a modified login page. In addition to the regular username/password fields, there should be a button like "Login with Plex" or the Plex logo.
- Click the "Login with Plex" button.
- You should be redirected to the Plex login page (either your local Plex server's login or app.plex.tv if your server is linked).
- Log in with valid Plex credentials (either your admin account or another Plex user account that has access to your server).
- After successful authentication with Plex, you should be redirected back to Organizr and automatically logged in.
- If you enabled "Allow New User Registrations via Plex":
  - If this was the first time this Plex user logged into Organizr, an Organizr account should have been created for them and added to the default group you specified.
  - Check their access: Do they see the tabs appropriate for that default group?
- If the Plex user already had an Organizr account with the same email address as their Plex account: Organizr might link the accounts, or it might depend on the specific version and configuration.
Verify as Administrator (Optional):
- Log out of the Plex-authenticated user session.
- Log back in as your Organizr administrator.
- Go to Settings -> Users -> User Management. If a new user was created via Plex login, you should see their account listed. You can then manage this account (e.g., change their group if needed) like any other Organizr user.

Troubleshooting:

Redirection Fails or Error on Plex Login:
- Ensure the Plex Server URL in Organizr settings is correct and reachable from the Organizr server.
- Check for firewall issues blocking communication between Organizr and Plex.
- If Plex itself is having issues, resolve those first.
Not Redirected Back to Organizr or Error After Plex Login:
- This can sometimes be due to reverse proxy misconfigurations if either Plex or Organizr (or both) are behind one. Ensure X-Forwarded-Proto and X-Forwarded-Host headers are correctly passed and trusted.
- The callback URL that Plex uses to redirect back to Organizr must be correct. Organizr usually handles this automatically.
"Login Failed" in Organizr after successful Plex Auth:
- Check Organizr logs for more details.
- Ensure the Plex user has access to the Plex server specified in Organizr's settings.
- If "Allow New User Registrations" was disabled and the Plex user didn't have a pre-existing Organizr account, login would fail.

You have now successfully configured Organizr to use Plex as an authentication method. This makes it much easier for users who are already familiar with Plex to access Organizr without needing to remember yet another password. This is a common and very useful SSO integration.

Securing Organizr with a Reverse Proxy and SSL

Accessing your Organizr dashboard and other self-hosted services securely, especially from outside your local network, is paramount. A reverse proxy combined with SSL/TLS certificates is the standard and most effective way to achieve this. This setup encrypts traffic, provides a professional appearance with custom domain names, and hides your internal network structure.

We'll focus on using NGINX Proxy Manager (NPM) for this, as it's user-friendly and integrates well with Let's Encrypt for free SSL certificates.

Core Components:

Domain Name: You need a domain name (e.g., your Mydomain.com) or a subdomain from a dynamic DNS provider (e.g., myorganizr.duckdns.org).
Dynamic DNS (if applicable): If you have a dynamic public IP address from your ISP, a DDNS service is needed to keep your domain name pointing to your changing IP.
Port Forwarding: You'll need to configure your router to forward external ports 80 (for HTTP, primarily for SSL certificate validation) and 443 (for HTTPS) to the internal IP address of the server where NGINX Proxy Manager will run.
NGINX Proxy Manager (NPM): This will be our reverse proxy, run as a Docker container.
Organizr (and other services): Running in their own Docker containers or as native services, accessible on your local network.

Pre-flight Checks:

Public IP: Know if your ISP provides you with a public IP address that you can port forward. Some ISPs use Carrier-Grade NAT (CGNAT), which makes direct port forwarding impossible. In CGNAT scenarios, you'd need a VPN/tunnel solution like Cloudflare Tunnel or Tailscale/ZeroTier to expose services. This guide assumes you do not have CGNAT and can port forward.
Router Access: You need administrative access to your home router to set up port forwarding.

Step 1: Set Up Your Domain and DDNS (if needed)

If using a paid domain: Configure an A record (e.g., organizr.yourdomain.com or a wildcard *.yourdomain.com) to point to your public IP. If your IP is dynamic, set up a DDNS service (like DuckDNS) and then point a CNAME record from your paid domain (e.g., organizr.yourdomain.com CNAME to yourddnschoice.duckdns.org).
If using a free DDNS hostname: Register a hostname (e.g., myawesomedashboard.duckdns.org) with a DDNS provider like DuckDNS. Install the DDNS update client on your server or configure it on your router to keep the IP address updated.

Step 2: Install NGINX Proxy Manager (NPM) via Docker Compose

Create a directory for NPM (e.g., ~/npm-docker or /opt/npm).
```
mkdir ~/npm-docker
cd ~/npm-docker
```

Create a docker-compose.yml for NPM:

nano docker-compose.yml

Paste the following:

version: '3.8'
services:
  app:
    image: 'jc21/nginx-proxy-manager:latest'
    container_name: nginx-proxy-manager
    restart: unless-stopped
    ports:
      # These ports are in format <host-port>:<container-port>
      - '80:8080'    # Public HTTP Port for SSL validation by Let's Encrypt
      - '443:4443'   # Public HTTPS Port for secure access
      - '81:8181'    # Admin Web UI Port
    volumes:
      - ./data:/data # Persistent data for NPM (configs, SSL certs)
      - ./letsencrypt:/etc/letsencrypt # Let's Encrypt certificates
    environment:
      # Set these to 'true' to enable deletion of default Nginx config files
      # Only enable if you know what you're doing
      # DELETE_DEFAULT_CONF: 'false' 
      # DELETE_DEFAULT_SERVER: 'false'
      # Set to your PUID and PGID to avoid permission issues on volumes
      PUID: 1000 # Replace with your PUID
      PGID: 1000 # Replace with your PGID
    # Optional: If you want NPM to be on a specific Docker network to easily reach other containers by name
    # networks:
    #  - proxy-network

# Optional: Define the custom network
# networks:
#   proxy-network:
#     driver: bridge

Important:
- Replace PUID and PGID with your user's values (use id command to find them).
- The ports 80:8080 and 443:4443 map host ports 80 and 443 to internal NPM ports. NPM listens on 8080 for HTTP and 4443 for HTTPS internally by default for proxied traffic. Port 81 on the host maps to NPM's admin UI on port 8181 internally.
- If host ports 80 or 443 are already in use by another application on your server, you'll need to stop that application or use different host ports (which is more complex for Let's Encrypt validation). Standard practice is for the primary reverse proxy to occupy 80 and 443.

Start NPM:
```
docker compose up -d
```

Step 3: Configure Port Forwarding on Your Router

Log in to your router's admin interface.
Find the "Port Forwarding," "NAT Forwarding," or "Virtual Servers" section.
Create two rules:
- Rule 1 (HTTP):
  - External Port: 80
  - Internal Port: 80
  - Protocol: TCP
  - Internal IP Address: The local IP address of the server running NGINX Proxy Manager.
- Rule 2 (HTTPS):
  - External Port: 443
  - Internal Port: 443
  - Protocol: TCP
  - Internal IP Address: The local IP address of the server running NGINX Proxy Manager.
Save the rules. Your firewall must also allow traffic on these ports to the NPM server.

Step 4: Initial NGINX Proxy Manager Setup

Access the NPM Admin UI: Open a web browser and go to http://<server_ip_running_npm>:81.
Default Admin Credentials:
- Email: admin@example.com
- Password: changeme
Immediately change the default username, email, and password to something secure.

Step 5: Add Organizr as a Proxy Host in NPM

In NPM, go to Hosts -> Proxy Hosts.
Click "Add Proxy Host".
Details Tab:
- Domain Names: Enter the domain name you want for Organizr (e.g., organizr.yourdomain.com or myorganizr.duckdns.org). Add www variants if desired (e.g. www.organizr.yourdomain.com).
- Scheme: http (assuming Organizr is listening on HTTP internally, which is typical when behind a reverse proxy).
- Forward Hostname / IP: The local IP address of the server where Organizr's Docker container is running (e.g., 192.168.1.100).
  - If NPM and Organizr are on the same Docker host and part of the same custom Docker network, you can often use the Organizr container name (e.g., organizr from your Organizr docker-compose.yml). This is more robust than using IPs if IPs might change.
- Forward Port: The host port Organizr is exposed on (e.g., 8999 if you mapped - "8999:80" in Organizr's docker-compose.yml). Or, if using Docker container names on a shared network, use the internal container port (usually 80 for Organizr).
- Cache Assets: Optional. Can improve performance for static assets.
- Block Common Exploits: Enable this. Provides basic protection.
- Websockets Support: Enable this. Organizr and many modern web apps use WebSockets.
SSL Tab:
- SSL Certificate: Select "Request a new SSL certificate" from the dropdown.
- Force SSL: Enable this. Automatically redirects HTTP requests to HTTPS.
- HTTP/2 Support: Enable this. For better performance.
- HSTS Enabled (Highly Recommended): Enable this. HTTP Strict Transport Security tells browsers to always use HTTPS for this site. You can leave the HSTS Max Age at default or increase it after thorough testing. Be cautious with HSTS Subdomains if you're not sure all subdomains will have HTTPS.
- Email Address for Let's Encrypt: Enter your valid email address.
- I Agree to the Let's Encrypt Terms of Service: Check the box.
Save. NPM will now attempt to obtain an SSL certificate from Let's Encrypt. This requires your domain to be correctly pointing to your public IP, and port 80 to be open and forwarded to NPM for the HTTP-01 challenge.
- If successful, the status will show "Online" with a green indicator.
- If it fails, check the logs (click the three dots next to the host entry -> View Log) for error messages. Common issues are incorrect DNS, port forwarding problems, or ISP blocking port 80.

Step 6: Test Access

Open your browser and navigate to https://organizr.yourdomain.com (or whatever domain you configured).
You should see your Organizr login page, served over HTTPS with a valid SSL certificate (padlock icon in the browser).

Step 7: (Recommended) Configure Organizr for Reverse Proxy

Log in to Organizr.
Go to Settings -> System -> Main Configuration (or similar path).
Look for settings related to "Base URL" or "Site URL." Set this to your full HTTPS domain name (e.g., https://organizr.yourdomain.com). This helps Organizr generate correct URLs.
Ensure "Behind a reverse proxy" or similar option is enabled if present, and that Organizr is configured to trust headers like X-Forwarded-For and X-Forwarded-Proto. Often, Organizr detects this automatically if the headers are passed correctly by NPM (which they usually are).

Security Headers (Optional but Recommended - Advanced NPM Configuration):

In NPM, when editing your proxy host, go to the "Advanced" tab. You can add custom NGINX configuration snippets here to further enhance security. Example:

# Add some security headers
add_header X-Frame-Options "SAMEORIGIN" always;
add_header X-Content-Type-Options "nosniff" always;
add_header Referrer-Policy "strict-origin-when-cross-origin" always;
# Content-Security-Policy is powerful but complex. Start with others first.
# add_header Content-Security-Policy "default-src 'self'; script-src 'self' 'unsafe-inline'; style-src 'self' 'unsafe-inline'; img-src 'self' data:;" always;

X-Frame-Options "SAMEORIGIN": Prevents clickjacking by not allowing your site to be iFramed by other domains. Organizr itself needs to iFrame services, so be careful if applying this globally vs. specifically for Organizr's public interface. Since Organizr is the dashboard, this is generally good for Organizr's own domain.
X-Content-Type-Options "nosniff": Prevents browsers from MIME-sniffing a response away from the declared content-type.
Referrer-Policy: Controls how much referrer information is sent.
Content-Security-Policy (CSP): A powerful header to prevent XSS attacks. It requires careful configuration and can easily break things if too restrictive. Start with simpler headers first.

You have now significantly hardened your Organizr setup by placing it behind NGINX Proxy Manager with a valid SSL certificate. You can repeat Step 5 for your other self-hosted services (Sonarr, Radarr, etc.), giving each its own subdomain and SSL protection, all managed through NPM's friendly interface.

Workshop: Securing Organizr with NGINX Proxy Manager and Let's Encrypt

Goal:
To configure NGINX Proxy Manager (NPM) to serve your Organizr instance over HTTPS using a custom domain/subdomain and a free SSL certificate from Let's Encrypt.

Prerequisites:

Organizr Running: Your Organizr instance is installed (via Docker preferably) and accessible on your local network (e.g., http://192.168.1.100:8999).
Docker Environment: Docker and Docker Compose are installed on your server.
Domain/Subdomain: You have a domain name (e.g., mydashboard.example.com) or a DDNS hostname (e.g., myorg.duckdns.org) that you control and can point to your server's public IP address.
- For this workshop, we'll assume you're using a DDNS hostname like your-unique-name.duckdns.org. If using your own domain, adapt accordingly.
DDNS Client Configured (if IP is dynamic): Your DDNS hostname is actively being updated with your current public IP address.
NGINX Proxy Manager Not Yet Installed: We will install it as part of this workshop. If it's already installed, ensure it's operational.
Router Access: You can configure port forwarding on your home router.

Workshop Steps:

Part 1: Point Your Domain/DDNS to Your Public IP

If using DuckDNS:
- Go to duckdns.org and log in.
- Create or update a subdomain (e.g., my-organizr-workshop) to point to your current public IP address. DuckDNS usually auto-detects your IP.
- Ensure you have a DuckDNS client running on your server or router to keep this IP updated. A simple cron job with curl can do this:
```
# Example cron entry (run `crontab -e`)
# */5 * * * * curl -k "https://www.duckdns.org/update?domains=my-organizr-workshop&token=YOUR_DUCKDNS_TOKEN&ip=" >/dev/null 2>&1
# Replace my-organizr-workshop and YOUR_DUCKDNS_TOKEN
```
If using your own domain:
- Log into your domain registrar's DNS management panel.
- Create an A record for your chosen subdomain (e.g., organizr.yourdomain.com) pointing to your public IP address.
- If your IP is dynamic, you'd typically create a CNAME record (e.g., organizr.yourdomain.com CNAME to your-ddns-hostname.duckdns.org).

Part 2: Install NGINX Proxy Manager (NPM)

Create NPM Directory and Docker Compose File:

SSH into your server.
Create a directory for NPM:
```
mkdir ~/npm-data
cd ~/npm-data
```
Create docker-compose.yml for NPM:
```
nano docker-compose.yml
```

Paste the following, replacing 1000 with your actual PUID/PGID if different (use id command to check your user):

version: '3.8'
services:
  app:
    image: 'jc21/nginx-proxy-manager:latest'
    container_name: npm
    restart: unless-stopped
    ports:
      - '80:8080'    # For Let's Encrypt HTTP-01 challenge
      - '443:4443'   # For HTTPS traffic
      - '81:8181'    # For NPM Admin UI
    volumes:
      - ./data:/data
      - ./letsencrypt:/etc/letsencrypt
    environment:
      PUID: 1000 # Your user ID
      PGID: 1000 # Your group ID
    # Optional: Add to a common Docker network if Organizr is on one
    # networks:
    #   - my_proxy_network

# Optional: Define the network
# networks:
#   my_proxy_network:
#     external: true # If created elsewhere, or define it here

Explanation of Port Mappings:
- 80:8080: Host port 80 (standard HTTP) maps to NPM's internal port 8080 where it expects HTTP traffic for proxied sites.
- 443:4443: Host port 443 (standard HTTPS) maps to NPM's internal port 4443 where it expects HTTPS traffic for proxied sites.
- 81:8181: Host port 81 maps to NPM's admin UI on internal port 8181. You'll access NPM admin via http://<your_server_ip>:81.

Start NGINX Proxy Manager:
```
docker compose up -d
```
Wait for it to download and start. Check with docker ps.

Part 3: Configure Router Port Forwarding

Log in to your router's administration page.
Find the "Port Forwarding" section.
Create two TCP port forwarding rules:
- Rule 1: External Port 80 -> Internal Port 80 -> IP Address of your server (where NPM is running).
- Rule 2: External Port 443 -> Internal Port 443 -> IP Address of your server.
Save the settings on your router.

Part 4: Initial NPM Setup (Login and Password Change)

Open a web browser and go to http://<your_server_local_ip>:81.
Log in with default credentials:
- Email: admin@example.com
- Password: changeme
You'll be prompted to change your details. Update the Full Name, Nickname, Email, and set a new strong password. Save.

Part 5: Add Organizr as a Proxy Host in NPM

In the NPM dashboard, click on "Hosts" then "Proxy Hosts".
Click the "Add Proxy Host" button.
Details Tab:
- Domain Names: Enter your full public domain/subdomain for Organizr (e.g., my-organizr-workshop.duckdns.org or organizr.yourdomain.com).
- Scheme: Select http.
- Forward Hostname / IP: Enter the local IP address of your server where Organizr is running (e.g., 192.168.1.100).
  - If Organizr and NPM are on the same custom Docker network, you could use Organizr's container name.
- Forward Port: Enter the port Organizr is listening on (e.g., 8999 from your Organizr docker-compose.yml).
- Block Common Exploits: Toggle ON.
- Websockets Support: Toggle ON.
SSL Tab:
- SSL Certificate: From the dropdown, select "Request a new SSL certificate".
- Force SSL: Toggle ON. This makes sure all connections use HTTPS.
- HTTP/2 Support: Toggle ON.
- Email Address for Let's Encrypt: Enter your real email address (Let's Encrypt uses this for expiry notifications).
- I Agree to the Let's Encrypt Terms of Service: Check the box.
Click "Save".
- NPM will now try to contact Let's Encrypt to get an SSL certificate. This can take a minute.
- If successful, the status indicator next to your host entry will turn green and say "Online."

Part 6: Test Secure Access to Organizr

Open a new browser tab (preferably a private/incognito window to avoid cached redirects).
Navigate to https://<your_full_domain_for_organizr> (e.g., https://my-organizr-workshop.duckdns.org).
You should see your Organizr login page.
Check for the padlock icon in your browser's address bar, indicating a secure HTTPS connection. Click it to view certificate details; it should be issued by Let's Encrypt.

Part 7: (Recommended) Update Organizr's Base URL

Log in to Organizr using its new HTTPS URL.
Go to Organizr Settings -> System -> Main Configuration (or similar).
Find the "Base URL for Organizr" or "Site URL" field.
Enter your full HTTPS URL: https://<your_full_domain_for_organizr>
Save settings in Organizr.

Troubleshooting:

NPM SSL Request Fails:
- DNS Propagation: Your domain/subdomain might not yet be pointing to your public IP globally. Wait a bit or use a DNS checker tool.
- Port 80 Not Open/Forwarded: Let's Encrypt's HTTP-01 challenge requires access to your server on port 80 from the internet. Double-check router port forwarding and any server firewalls (like ufw). Test with an online port checker tool.
- ISP Blocking Port 80: Some residential ISPs block port 80. If so, you might need to use Let's Encrypt's DNS-01 challenge, which is more complex to set up in NPM (often requires API access to your DNS provider).
- NPM Logs: In NPM, click the three dots next to your proxy host entry and "View Log" to see error details from Let's Encrypt.
"502 Bad Gateway" Error After Setup:
- NPM cannot reach your Organizr backend.
- Verify the "Forward Hostname / IP" and "Forward Port" in NPM are correct for your Organizr instance.
- Ensure Organizr container is running.
- Check for firewall issues on the server blocking NPM from connecting to Organizr's port.
- If using Docker container names, ensure both NPM and Organizr are on the same custom Docker network.

You have now successfully secured your Organizr dashboard with HTTPS using NGINX Proxy Manager and Let's Encrypt! This is a critical step for secure remote access and a professional setup. You can repeat Part 5 for any other self-hosted services you want to expose securely.

Advanced NGINX Configuration for Organizr

Organizr itself runs on an NGINX web server internally within its Docker container. While Organizr's default NGINX configuration is robust and suitable for most users, there might be scenarios where you need to customize it. This could involve adding custom location blocks, modifying headers for specific paths, setting up custom error pages, or integrating more deeply with Organizr's SSO capabilities via NGINX directives.

Understanding Organizr's Internal NGINX:

The Organizr Docker image comes with a pre-configured NGINX instance that serves the Organizr PHP application and static files.
The main NGINX configuration files (nginx.conf, site configurations in sites-available or conf.d) are located within the container, typically under /etc/nginx/.
Organizr's developers provide a structured way to allow user customizations, often by including files from specific directories within the /config volume that you map from your host.

Common Customization Paths (Check Organizr Documentation for Exact Paths):

Organizr's Docker setup usually allows you to place custom NGINX configuration snippets in specific subdirectories of your main /config volume. These snippets are then included into the main NGINX configuration by Organizr's default setup. Common locations might include:

/config/nginx/site-confs/default.conf or similar for modifying the main server block.
/config/nginx/proxy-confs/ for custom proxy configurations.
/config/nginx/custom-locations.conf for adding new location blocks.
/config/nginx/nginx.conf (less common to override fully, usually snippets are preferred).

It is CRUCIAL to consult the official Organizr documentation or their Discord community for the precise and recommended way to add custom NGINX configurations for your version of Organizr, as these paths and include mechanisms can change. Incorrectly modifying NGINX configs can break your Organizr instance.

Typical Use Cases for Custom NGINX Configuration:

Custom Error Pages:

Instead of NGINX's default error pages (e.g., for 404 Not Found, 500 Internal Server Error), you can specify your own HTML pages.

Example snippet (to be placed in an appropriate .conf file included by Organizr's NGINX):

# In your custom NGINX conf snippet
error_page 403 /custom_403.html;
error_page 404 /custom_404.html;
error_page 500 502 503 504 /custom_50x.html;

location = /custom_403.html {
    root /config/www/errors; # Assuming you place custom_403.html here
    internal; # Makes it only accessible internally via NGINX error handling
}
location = /custom_404.html {
    root /config/www/errors;
    internal;
}
location = /custom_50x.html {
    root /config/www/errors;
    internal;
}

You would then need to create these HTML files (e.g., custom_404.html) and place them in a directory accessible to NGINX inside the container, like /config/www/errors (which you'd map from your host).

Adding Custom Headers for Specific Paths:
- You might want to add or modify HTTP headers for certain parts of your Organizr site.
- Example: Add a stricter X-Frame-Options for a specific API path.
```
location /api/v2/some_sensitive_endpoint {
    add_header X-Frame-Options "DENY" always;
    # other proxy_pass or processing directives for this API
}
```
Custom Location Blocks for Serving Static Content or Proxying to Internal Services:
- You could define a new path under your Organizr domain to serve specific static files or even proxy to another very simple internal-only service without exposing it through your main reverse proxy (NGINX Proxy Manager).
- Example: Serve a static status page at /my-status.
```
location /my-status/ {
    alias /config/www/mystatuspage/; # HTML files in /config/www/mystatuspage/
    index index.html;
    try_files $uri $uri/ =404;
}
```

Rate Limiting:

To protect against brute-force attacks on the login page or API endpoints, you can implement rate limiting.

Example (conceptual, requires limit_req_zone in http block, then used in location):

# In http block (might need to add to a higher-level custom NGINX conf)
# limit_req_zone $binary_remote_addr zone=login_limit:10m rate=1r/s;

# In your server block or location block for login
location = /auth/login { # Or whatever Organizr's login path is
    limit_req zone=login_limit burst=5 nodelay;
    # ... other directives for login processing
}

Modifying PHP-FPM Parameters for Organizr:
- Adjusting timeouts or buffer sizes for PHP processing if Organizr is performing long-running tasks. This is usually done in the NGINX directives that pass requests to PHP-FPM (e.g., fastcgi_read_timeout).

Mounting Custom NGINX Configuration Files:

To apply these custom configurations, you typically:

Create the custom .conf file on your Docker host (e.g., my_custom_nginx.conf).
Modify your Organizr docker-compose.yml to mount this file into the appropriate directory inside the Organizr container that NGINX is configured to include.
- Example docker-compose.yml snippet:
```
services:
  organizr:
    # ... other settings ...
    volumes:
      - ./config:/config # Standard Organizr config volume
      - ./my_custom_nginx_rules.conf:/config/nginx/site-confs/custom.conf:ro # Example path
      # The :ro makes it read-only in the container, good practice for config files
```
- Again, the target path /config/nginx/site-confs/custom.conf is an EXAMPLE. You MUST verify the correct include path from Organizr's official documentation.

Restart the Organizr Container:

docker compose restart organizr
# Or docker compose down && docker compose up -d

Test Thoroughly:

After restarting, test that Organizr still works and that your custom configurations are having the intended effect.

Check NGINX logs within the Organizr container if something is wrong:

docker exec -it organizr cat /config/log/nginx/error.log
# Or check the NGINX config syntax before restarting (if you can exec into a running container and run nginx -t)
# docker exec -it organizr nginx -t

Important Cautions:

Backup First: Before making any changes to NGINX configurations, ensure you have a backup of your Organizr /config volume.
Complexity: NGINX configuration can be powerful but also complex. A small syntax error can prevent NGINX from starting, making Organizr inaccessible.
Official Documentation is Key: The methods and paths for custom NGINX configuration are specific to how the Organizr Docker image is built and maintained. Always refer to the latest official Organizr documentation or seek advice from their community.
Reverse Proxy vs. Internal NGINX: For many common needs like SSL termination, custom headers for the entire site, or routing different domains/subdomains, it's often easier and cleaner to handle these at your main reverse proxy level (e.g., NGINX Proxy Manager, Traefik) rather than deep within Organizr's internal NGINX. Reserve internal NGINX customizations for things very specific to Organizr's operation or paths that are not exposed/handled by your main reverse proxy.

Advanced NGINX configuration offers fine-grained control but should be approached with caution and a good understanding of NGINX syntax and Organizr's specific include mechanisms.

Workshop: Adding a Custom NGINX Location Block for a Simple Internal Page

Goal: To serve a very simple, static HTML page from a custom path within your Organizr instance (e.g., https://organizr.yourdomain.com/internal-info) by adding a custom NGINX location block to Organizr's internal NGINX configuration.

Prerequisites:

Organizr is running via Docker Compose.
You are comfortable editing text files and your docker-compose.yml.
You have access to your Docker host's terminal.
You have reviewed Organizr's official documentation (or have reliable information from its community, like Discord) about the correct path inside the container where custom NGINX configuration snippets should be placed to be included by the main NGINX server.
- Disclaimer: The paths used below (/config/nginx/custom-conf.d/) are illustrative. This path might be different for your Organizr version. This workshop assumes Organizr's NGINX is set up to include *.conf files from a directory like /config/nginx/custom-conf.d/. Verify this path! A common pattern for Organizr v2 is to put custom server block modifications in /config/nginx/site-confs/default.conf or for Organizr to look for includes in /config/nginx/conf.d/ or similar. We will proceed with a hypothetical include directory.

Workshop Steps:

Create the Static HTML Page on Your Docker Host:

On your Docker host machine, create a directory structure that will be mapped into the Organizr container. This will hold your static HTML page.
```
# In your main Organizr Docker project directory (e.g., ~/organizr-docker or where your Organizr docker-compose.yml is)
mkdir -p appdata/www/internal_docs 
cd appdata/www/internal_docs
```
- We use appdata here as a common name for persistent application data that we might map into containers.
Create a simple HTML file named info.html inside ~/organizr-docker/appdata/www/internal_docs/:
```
nano info.html
```

Paste the following HTML content:

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <title>Internal Information</title>
    <style>
        body { font-family: sans-serif; margin: 20px; background-color: #f0f0f0; }
        h1 { color: #333; }
        p { color: #555; }
    </style>
</head>
<body>
    <h1>Welcome to Our Internal Info Page!</h1>
    <p>This page is served directly by Organizr's internal NGINX via a custom location block.</p>
    <p>Current Date/Time on Server (approx): <span id="datetime"></span></p>
    <script>
        document.getElementById('datetime').textContent = new Date().toLocaleString();
    </script>
</body>
</html>

Save and exit (Ctrl+X, then Y, then Enter in nano).

Create the Custom NGINX Configuration Snippet on Your Docker Host:
- Go back to your main Organizr Docker project directory (e.g., ~/organizr-docker).
- Create a directory for your custom NGINX snippets (this directory name on the host doesn't strictly matter, but its target path inside the container does).
```
mkdir -p nginx_custom_conf
cd nginx_custom_conf
```
- Create a new NGINX configuration file, e.g., internal_info_location.conf:
```
nano internal_info_location.conf
```
- Paste the following NGINX configuration. Note the alias path reflects where info.html will be inside the container after we set up the volume mount in docker-compose.yml.
```
# Custom location block for /internal-info
location /internal-info/ {
    alias /app/www/internal_docs/; # Path INSIDE the Organizr container
    index info.html;
    try_files $uri $uri/ =404;

    # Optional: Restrict access to local network or specific IPs
    # allow 192.168.1.0/24; # Allow local network
    # allow YOUR_VPN_IP;    # Allow your VPN IP
    # deny all;             # Deny all other IPs
}
```
  - Explanation:
    - location /internal-info/ { ... }: Defines a block that NGINX will use if the request URL starts with /internal-info/.
    - alias /app/www/internal_docs/;: This is crucial. It tells NGINX that requests to /internal-info/ should be served from the /app/www/internal_docs/ directory inside the container. The alias directive maps the URL path to a filesystem path. The trailing slash on both location and alias is important for alias to work correctly.
    - index info.html;: If a request is made to /internal-info/ (without a filename), NGINX will look for info.html.
    - try_files $uri $uri/ =404;: Standard practice. Tries to serve the requested file, then a directory, otherwise returns a 404 error.
    - The commented-out allow/deny lines show how you could restrict access. For this workshop, we'll leave it open.

Modify docker-compose.yml to Mount Custom Files/Directories:

Open your Organizr docker-compose.yml file.
You need to add two new volume mounts:
1. Mount your host's appdata/www/internal_docs directory (containing info.html) to /app/www/internal_docs inside the container.
2. Mount your host's nginx_custom_conf/internal_info_location.conf file to the location inside the container where Organizr's NGINX will include it. THIS IS THE CRITICAL PART YOU MUST VERIFY FROM ORGANIZR DOCS.
  - Let's assume Organizr includes files from /config/nginx/custom-conf.d/. So, we'll mount our file as /config/nginx/custom-conf.d/internal_info_location.conf.

Your services: organizr: volumes: section might look something like this (add the new lines):

# ... (other docker-compose settings) ...
services:
  organizr:
    image: organizr/organizr:latest # Or your specific version
    container_name: organizr
    # ... (other organizr settings like ports, environment, PUID/PGID) ...
    volumes:
      - ./config:/config  # Standard Organizr config volume
      # ---- ADD THESE NEW LINES ----
      - ./appdata/www/internal_docs:/app/www/internal_docs:ro # Mount for our HTML page (read-only)
      - ./nginx_custom_conf/internal_info_location.conf:/config/nginx/custom-conf.d/internal_info_location.conf:ro # Mount for our NGINX snippet (read-only)
                                                            # ^^^ VERIFY THIS TARGET PATH with Organizr docs!
    # ... (other settings like restart policy) ...

The :ro makes the mounts read-only inside the container, which is good practice for static content and configuration files that shouldn't be changed by the container itself.

Restart Organizr to Apply Changes:
- Navigate to the directory containing your Organizr docker-compose.yml.
- bash docker compose down docker compose up -d # Or: docker compose restart organizr
Test Access to the Custom Page:
- Open your web browser.
- Navigate to your Organizr URL followed by /internal-info/ or /internal-info/info.html.
  - If Organizr is at http://localhost:8999, try http://localhost:8999/internal-info/
  - If Organizr is at https://organizr.yourdomain.com (behind NPM), try https://organizr.yourdomain.com/internal-info/
- You should see your custom "Internal Information" HTML page.

Troubleshooting:

404 Not Found Error:
- NGINX Config Path: The most likely issue is that the target path for your internal_info_location.conf inside the container (/config/nginx/custom-conf.d/internal_info_location.conf in our example) is incorrect, and Organizr's NGINX is not actually including your snippet. TRIPLE-CHECK THE CORRECT INCLUDE PATH FROM OFFICIAL ORGANIZR DOCUMENTATION.
- alias Path: Ensure the alias path in internal_info_location.conf (/app/www/internal_docs/) exactly matches the target path of your HTML content volume mount in docker-compose.yml.
- File/Directory Permissions: Less likely with Docker volume mounts from the host if PUID/PGID are set correctly for the main /config volume, but ensure NGINX (running as a specific user inside the container) can read the mounted files.
- Typos: Check for typos in filenames, paths in NGINX config, and docker-compose.yml.
- NGINX Logs: Check NGINX error logs inside the Organizr container:
```
docker exec -it organizr cat /config/log/nginx/error.log
docker exec -it organizr cat /var/log/nginx/error.log # Alternative path for some setups
```
- NGINX Syntax Check: If possible, test NGINX config syntax:
```
docker exec -it organizr nginx -t
```
  This will tell you if there's a syntax error in any NGINX config file it loads.
Organizr Fails to Start: Likely a fatal syntax error in your custom NGINX snippet or an issue with how it's included. Revert the changes to docker-compose.yml and the custom NGINX file, restart Organizr to get it working again, then troubleshoot the NGINX snippet carefully.

This workshop demonstrates a common advanced NGINX customization. The key takeaway is the importance of understanding Organizr's specific NGINX include structure and meticulous path management in both your NGINX configuration and Docker volume mounts.

Backups and Disaster Recovery

A robust backup and disaster recovery plan is non-negotiable for any self-hosted service, and Organizr is no exception. Your Organizr instance holds valuable configuration: user accounts, tab setups, homepage item configurations, theme customizations, and potentially an SQLite database. Losing this data would mean rebuilding your entire dashboard from scratch. This section outlines strategies for backing up Organizr and restoring it in case of data loss or system failure.

Identifying Critical Organizr Data:

When using Organizr with Docker (and Docker Compose), the critical data is almost entirely contained within the volume you mapped to /config inside the Organizr container.

Primary Data Location: The directory on your Docker host that you mapped to /config in your docker-compose.yml.
- Example from previous workshops: ~/my-organizr/data or ~/organizr-docker/config.
Contents of this Directory:
- Database: If using SQLite (default), the database file (e.g., organizr.db or similar, often in a DB subdirectory) is here. This is the most critical file.
- Configuration Files: Various .json, .ini, or .php files storing settings, user preferences, tab configurations, etc. (e.g., config.php, users.json).
- NGINX Customizations: If you've added custom NGINX snippets, they reside here (e.g., in /config/nginx/).
- Custom Themes/CSS/Images: Any uploaded themes, logos, favicons, or custom CSS files.
- Logs: Log files (e.g., /config/log/nginx/, /config/log/php/, /config/log/organizr/). While not always critical to restore, they can be useful for troubleshooting.
If using external MySQL/MariaDB: Your Organizr database is not in the /config volume. You must back up this external database separately using database-specific tools (like mysqldump). This guide primarily focuses on the more common SQLite setup.

Backup Strategies for Docker Volumes:

Manual Backup (Simple Tarball):

Method: Stop the Organizr container, create a compressed archive (e.g., .tar.gz) of the /config volume directory, and then restart the container.
Pros: Simple to implement, good for ad-hoc backups.
Cons: Requires downtime (briefly stopping Organizr), manual process prone to being forgotten.

Commands:

# Navigate to the directory containing your Organizr docker-compose.yml
cd ~/my-organizr # Or your Organizr project directory

# 1. Stop Organizr
docker compose down

# 2. Create the backup (assuming 'data' is your mapped config volume name)
# The backup will be created one level above your 'data' directory
tar -czvf ../organizr_backup_$(date +%Y%m%d_%H%M%S).tar.gz ./data
# Example: if ./data is /home/user/my-organizr/data, backup is /home/user/my-organizr_backup_....tar.gz

# 3. Restart Organizr
docker compose up -d

# 4. (Important!) Move the backup file to a separate, secure location
# (e.g., another drive, cloud storage, a NAS).
# mv ../organizr_backup_YYYYMMDD_HHMMSS.tar.gz /mnt/backups/organizr/

Automated Scripted Backup (Cron Job):

Method: Create a shell script that performs the steps for a manual backup (stop container, tar, start container) and schedule it to run regularly using cron.
Pros: Automated, reduces risk of forgetting backups.
Cons: Still involves brief downtime during the backup. Script needs to be robust (handle errors, manage old backups).

Example Script (backup_organizr.sh):

#!/bin/bash
set -e # Exit immediately if a command exits with a non-zero status.

ORGANIZR_COMPOSE_DIR="/home/user/my-organizr" # Path to Organizr's docker-compose.yml directory
ORGANIZR_CONFIG_DIR_NAME="data"             # Name of the config directory relative to COMPOSE_DIR
BACKUP_DEST_DIR="/mnt/backups/organizr"     # Destination for backups
TIMESTAMP=$(date +%Y%m%d_%H%M%S)
BACKUP_FILE_NAME="organizr_backup_${TIMESTAMP}.tar.gz"

# Ensure backup destination exists
mkdir -p "${BACKUP_DEST_DIR}"

echo "Starting Organizr backup: ${TIMESTAMP}"

# Navigate to Organizr directory
cd "${ORGANIZR_COMPOSE_DIR}" || { echo "Failed to cd to ${ORGANIZR_COMPOSE_DIR}"; exit 1; }

# Stop Organizr
echo "Stopping Organizr..."
docker compose down
echo "Organizr stopped."

# Create backup
echo "Creating backup of ./${ORGANIZR_CONFIG_DIR_NAME} to ${BACKUP_DEST_DIR}/${BACKUP_FILE_NAME}..."
tar -czf "${BACKUP_DEST_DIR}/${BACKUP_FILE_NAME}" "./${ORGANIZR_CONFIG_DIR_NAME}"
echo "Backup created."

# Restart Organizr
echo "Starting Organizr..."
docker compose up -d
echo "Organizr started."

# Optional: Prune old backups (e.g., keep last 7)
echo "Pruning old backups in ${BACKUP_DEST_DIR} (keeping last 7)..."
ls -1t "${BACKUP_DEST_DIR}"/organizr_backup_*.tar.gz | tail -n +8 | xargs -r rm
echo "Pruning complete."

echo "Organizr backup finished successfully: ${TIMESTAMP}"

Make the script executable: chmod +x backup_organizr.sh.
Schedule with crontab -e (e.g., 0 3 * * * /path/to/backup_organizr.sh >> /var/log/organizr_backup.log 2>&1 to run daily at 3 AM).

Dedicated Backup Tools (Recommended for Robustness):
- Duplicati, Restic, BorgBackup, Kopia, Vorta (Borg GUI): These are powerful open-source backup tools that offer features like:
  - Deduplication (saves storage space).
  - Encryption (secures backups).
  - Compression.
  - Scheduling.
  - Multiple backup destinations (local, cloud storage like S3, Backblaze B2, SFTP, etc.).
  - Retention policies (automatically manage old backups).
  - Some can perform backups of directories while services are running, though for databases, a "cold" backup (service stopped) or a proper database dump is safer to ensure consistency. For Organizr's SQLite, stopping it briefly is the safest.
- Method: Configure the backup tool to back up your Organizr /config host directory. You might still script stopping/starting Organizr around the backup tool's execution if it doesn't handle live file locking well for SQLite.
- Pros: Feature-rich, reliable, efficient.
- Cons: Steeper learning curve than simple tar.

Backup Best Practices (3-2-1 Rule):

3 Copies: Keep at least three copies of your important data.
2 Different Media: Store the copies on at least two different types of storage media (e.g., internal drive + external USB drive, or internal drive + NAS).
1 Offsite Copy: Keep at least one copy offsite (e.g., cloud storage, a drive at a friend's house) to protect against local disasters like fire, flood, or theft.

Restoring Organizr from a Backup:

The restore process depends on how you backed up, but the general idea is to replace the contents of your Organizr /config host directory with the contents from your backup.

Identify the Backup: Locate the backup file or snapshot you want to restore from.

Stop Organizr:

# In your Organizr docker-compose project directory
docker compose down

Prepare the Config Directory:
- It's wise to rename or move the current (potentially corrupted) /config host directory rather than deleting it immediately, just in case.
```
# Example: if your config dir is ./data
mv ./data ./data_corrupted_$(date +%Y%m%d)
mkdir ./data # Recreate the empty directory
```
Restore Files:
- If using a tar.gz backup:
```
# Assuming backup is ../organizr_backup_file.tar.gz and target is ./data
tar -xzvf /path/to/your/organizr_backup_file.tar.gz -C ./
# This should extract the contents into the ./data directory (or whatever was archived)
# Ensure the restored directory structure matches what Organizr expects (e.g. if you backed up 'data', restore 'data')
# If tar extracted into a subdirectory, move contents up:
# Example: if tar -xzvf created ./backup_root/data/*, you might need to move ./backup_root/data/* to ./data/
```
  A safer tar extraction, assuming the archive contains the data directory itself at the root: tar -xzvf /path/to/your/organizr_backup_file.tar.gz This will recreate the data directory (or whatever root folder was in the tarball) in the current location. Ensure this is the correct path defined in your docker-compose.yml. If the archive contains only the contents of data but not data itself, then: tar -xzvf /path/to/your/organizr_backup_file.tar.gz -C ./data (after mkdir ./data)
- If using a backup tool (Duplicati, Restic, etc.): Use the tool's restore command to restore the files to the original /config host directory path.
Check Permissions (Crucial):
- After restoring, ensure the ownership and permissions of the restored files and directories match what Organizr expects. The PUID and PGID you set in docker-compose.yml should own these files.
- bash # Example: if PUID/PGID correspond to user 'youruser' and group 'yourgroup' sudo chown -R youruser:yourgroup ./data
Restart Organizr:
```
docker compose up -d
```
Test Thoroughly:
- Access Organizr. Check if your settings, users, tabs, and homepage items are all restored correctly.
- Review logs for any errors.

Regularly Test Your Restore Process! Backups are useless if you can't restore them. Periodically perform a test restore to a non-production environment or a temporary directory to ensure your backup strategy is working correctly.

By implementing a solid backup strategy and knowing how to restore, you protect your valuable Organizr configuration and ensure you can recover quickly from any unforeseen incidents.

Workshop: Performing and Testing a Manual Backup and Restore of Organizr

Goal: To manually back up your Organizr configuration data, simulate a data loss scenario, and then restore Organizr from the backup to ensure the process works.

Prerequisites:

Organizr is running via Docker Compose.
You know the path on your Docker host that is mapped to /config inside the Organizr container (e.g., ~/my-organizr/data or ~/organizr-docker/config). For this workshop, we'll assume this path is ~/my-organizr/data.
You have terminal access to your Docker host.

Workshop Steps:

Part 1: Performing the Manual Backup

Navigate to Your Organizr Project Directory:
- Open a terminal on your Docker host.
- Change to the directory where your Organizr docker-compose.yml file is located.
```
cd ~/my-organizr
# This directory should contain your 'data' subdirectory (the config volume)
```
Identify and Verify Configuration Data (Optional but good practice):
- List the contents of your Organizr configuration directory to see what's there.
```
ls -l ./data
# You should see files and subdirectories like DB, log, nginx, config.php, etc.
```
Stop the Organizr Container:
- This ensures data consistency during the backup, especially for the SQLite database.
```
docker compose down
```
- Verify it's stopped: docker ps (Organizr should not be listed).

Create a Compressed Archive (Backup):

We'll create a tar.gz archive of the data directory. The backup file will be placed one level up from the my-organizr directory to keep it separate.

# Command explained:
# tar: the archiving utility
# -c: create an archive
# -z: compress with gzip
# -v: verbose output (shows files being archived)
# -f ../organizr_manual_backup_$(date +%Y%m%d_%H%M%S).tar.gz: specifies the filename for the archive.
#    ../ means one directory up.
#    $(date +%Y%m%d_%H%M%S) adds a timestamp to the filename.
# ./data: the directory to archive.
tar -czvf ../organizr_manual_backup_$(date +%Y%m%d_%H%M%S).tar.gz ./data

You should see a list of files being added to the archive.

Verify the backup file was created:

ls -lh ../organizr_manual_backup_*.tar.gz

Restart the Organizr Container (Optional for now, as we'll simulate disaster next):
- Normally, after a backup, you'd restart your service. For this workshop, we'll keep it down to simulate the "disaster."
```
# Normally you would do:
# docker compose up -d
# But we will skip this for the next step.
```

Part 2: Simulating Data Loss

"Disaster" Strikes – Remove/Rename the Original Config Directory:
- We will rename the original data directory to simulate it being lost or corrupted. Be careful with rm commands; renaming (mv) is safer for simulations.
```
# Ensure you are in the ~/my-organizr directory
# Rename the current data directory to simulate its loss
mv ./data ./data_OLDSIMULATED_DISASTER_$(date +%Y%m%d)
```
- Verify that the data directory is gone (or renamed):
```
ls -l
# You should see 'data_OLDSIMULATED_DISASTER_...' but not 'data'.
```
- At this point, if you tried to start Organizr, it would act like a fresh install because its config is "gone."

Part 3: Restoring Organizr from Backup

Locate Your Backup File:
- Our backup file is in the parent directory (e.g., ~/organizr_manual_backup_YYYYMMDD_HHMMSS.tar.gz). Note its full path. Let's assume it's ../organizr_manual_backup_20231027_100000.tar.gz for example.

Ensure Organizr is Stopped: (It should still be stopped from Part 1, but good to confirm)

docker ps # Organizr should not be running
# If it was accidentally started, stop it: docker compose down

Create an Empty Target Directory (if it doesn't exist after renaming):
- The tar command can recreate the top-level directory from the archive if it was archived that way. If our archive contains data/... at its root, we just need to be in ~/my-organizr. If it contains contents_of_data/..., we need to create data first.
- Our tar command (tar ... ./data) archived the data directory itself. So when we extract it in ~/my-organizr, it will recreate ./data.

Extract the Backup Archive:

Extract the contents of your backup file into the current directory (~/my-organizr). This should recreate the ./data directory and its contents.

# Replace with your actual backup filename
tar -xzvf ../organizr_manual_backup_YYYYMMDD_HHMMSS.tar.gz
# Example: tar -xzvf ../organizr_manual_backup_20231027_100000.tar.gz

Verify the data directory is restored:

ls -l
ls -l ./data
# You should see the 'data' directory and its original contents.

Verify Ownership/Permissions (Important - though often fine with host mounts):
- The extracted files should typically retain the ownership/permissions they had when archived. If your PUID/PGID in docker-compose.yml corresponds to your current user who created the archive, this is usually fine.
- If you suspect issues, you might need sudo chown -R YOUR_USER:YOUR_GROUP ./data where YOUR_USER:YOUR_GROUP corresponds to the PUID/PGID. For this workshop, we'll assume permissions are okay.

Part 4: Starting Organizr and Verifying Restoration

Start the Organizr Container:
```
docker compose up -d
```
Wait for Organizr to Start and Test:
- Give it a minute to initialize.
- Access your Organizr instance via your web browser.
- Verification Checklist:
  - Can you log in with your previous user credentials?
  - Are your tabs configured as they were before the "disaster"?
  - Are your homepage items present and displaying data (they might need a moment to refresh)?
  - Is your theme and custom appearance restored?
  - Are other users (if any) and their permissions intact?

If everything looks as it did before you simulated the disaster, your backup and restore process was successful!

Important Cleanup:

You can now delete the simulated disaster directory if you wish:
```
rm -rf ./data_OLDSIMULATED_DISASTER_*
```
Crucially, move your actual backup file (../organizr_manual_backup_....tar.gz) to a secure, separate storage location (another drive, cloud, NAS). A backup stored on the same drive as the original data isn't safe from drive failure.

This workshop provides confidence that you can recover your Organizr setup. For production, automate this process and follow the 3-2-1 backup rule.

Troubleshooting Common Organizr Issues

Even with a well-configured setup, you might occasionally encounter issues with Organizr or its integrated services. Knowing how to approach troubleshooting is key to resolving problems efficiently. This section covers common problems and general diagnostic techniques.

1. Blank Pages or iFrame Loading Problems:

Symptom: A tab in Organizr shows a blank page, an error message from the service (like "refused to connect"), or the service's UI looks broken.
Common Causes & Solutions:
- X-Frame-Options or Content-Security-Policy: frame-ancestors: The most common culprit. The target service is configured to prevent itself from being embedded in an iFrame on a different domain (or any iFrame).
  - Diagnosis: Open your browser's Developer Tools (usually F12). Go to the "Console" tab. Look for errors like:
    - Refused to display 'URL' in a frame because it set 'X-Frame-Options' to 'SAMEORIGIN' or 'DENY'.
    - Refused to frame 'URL' because an ancestor violates the following Content Security Policy directive: "frame-ancestors 'self' ...".
  - Solution (if you control the service):
    - Modify the service's web server configuration (NGINX, Apache, Caddy for that specific service) to allow iFraming from your Organizr domain.
      - For NGINX: add_header X-Frame-Options "ALLOW-FROM https://organizr.yourdomain.com"; (Note: ALLOW-FROM has limited browser support).
      - Better: add_header Content-Security-Policy "frame-ancestors https://organizr.yourdomain.com 'self';";
      - Or, if less security is acceptable for that service: add_header X-Frame-Options ""; (removes header) or add_header X-Frame-Options "ALLOWALL"; (non-standard but some apps use it).
    - Some applications have settings within their own UI to configure X-Frame-Options or allowed iFrame origins.
  - Solution (if you don't control the service or can't change headers): Change the Organizr tab type from "iFrame" to "External Link."
- Mixed Content: If Organizr is served over HTTPS (e.g., https://organizr.yourdomain.com) but the iFramed service is served over HTTP (e.g., http://192.168.1.50:8080). Modern browsers block insecure active content (like an HTTP iFrame) on a secure HTTPS page.
  - Diagnosis: Look for "Mixed Content" errors in the browser console.
  - Solution:
    - Best: Ensure the target service is also served over HTTPS (e.g., put it behind your reverse proxy like NGINX Proxy Manager and assign it an SSL certificate).
    - If the service is only accessible locally via HTTP, and Organizr is accessed via HTTPS externally, this will be an issue. Your reverse proxy should be able to proxy this internal HTTP service and present it as HTTPS to the Organizr iFrame.
- Service URL Incorrect or Service Down: The URL in the Organizr tab configuration is wrong, or the service itself is not running or not reachable from the Organizr server.
  - Diagnosis: Try accessing the service's URL directly in a new browser tab. Check Organizr's "Ping" status for the tab (if enabled).
  - Solution: Correct the URL in Organizr's Tab Editor. Ensure the service is running and accessible.
- Network Issues/DNS Resolution: If Organizr (especially its container) cannot resolve the hostname or reach the IP of the iFramed service.
  - Diagnosis: docker exec -it <organizr_container_name> ping <service_hostname_or_ip> or curl <service_url>.
  - Solution: Fix Docker networking, DNS settings for the container, or firewall rules.

2. Login Issues:

Symptom: Unable to log in to Organizr, password not accepted, SSO login fails.
Common Causes & Solutions:
- Incorrect Credentials: Double-check username and password. Caps Lock?
- Cookies/Browser Cache: Stale cookies or cached data can interfere.
  - Solution: Clear browser cookies and cache for the Organizr site, or try an incognito/private browsing window.
- SSO Misconfiguration (e.g., Plex SSO):
  - Plex server URL incorrect in Organizr settings.
  - Plex server down or unreachable by Organizr.
  - Callback URL issues (often related to reverse proxy setup if X-Forwarded-Proto/Host are not set/trusted correctly).
  - Diagnosis: Check Organizr logs (Settings -> System -> View Log or Docker logs) for SSO-related errors. Check browser console during the SSO redirect flow.
  - Solution: Verify all SSO settings in Organizr and ensure the SSO provider (e.g., Plex) is operational and configured correctly.
- Database Issues (Rare): If the Organizr database (SQLite or external) is corrupted, it could affect logins.
  - Diagnosis: Check Organizr logs for database errors.
  - Solution: Restore from backup.
- Fail2Ban or IP Blocking: If Organizr or a reverse proxy in front of it has IP blocking (like Fail2Ban) enabled, too many failed login attempts might have banned your IP.
  - Solution: Check Fail2Ban logs/status and unban your IP if necessary.

3. Organizr Container Not Starting or Crashing:

Symptom: docker ps shows the Organizr container is constantly restarting, in an "Exited" state, or not present after attempting to start. docker compose up (without -d) might show immediate errors and exit.
Common Causes & Solutions:
- Incorrect docker-compose.yml Configuration:
  - Syntax Errors: Typos, incorrect indentation, or improper YAML structure in your docker-compose.yml file.
    - Diagnosis: Before starting, run docker compose config in the directory containing your docker-compose.yml. This command validates the syntax and effective configuration. If there are errors, it will point them out.
    - Solution: Carefully review the docker-compose.yml file, paying close attention to spacing (YAML is very sensitive to indentation, usually 2 spaces per level), colons, hyphens, and quoting. Compare with official examples.
  - Incorrect Volume Paths: The host path specified for the /config volume mount might not exist, or there might be permission issues with accessing it before the container even fully starts its internal processes.
    - Diagnosis: docker compose up (without -d) will show logs in the foreground. Docker itself might report errors about being unable to mount the specified volume.
    - Solution: Verify that the host-side path for your main Organizr configuration volume (e.g., ./config or /opt/organizr/config) exists. Ensure Docker has the necessary permissions to access this path (though PUID/PGID usually handles permissions within the volume once mounted).
  - Port Conflicts on the Host: The host port you're trying to map for Organizr (e.g., 8999:80) might already be in use by another application on your Docker host.
    - Diagnosis: docker compose up will show an error message like "Error starting userland proxy: listen tcp 0.0.0.0:8999: bind: address already in use." You can also use sudo netstat -tulnp | grep :<port_number> or ss -tulnp | grep :<port_number> on the host to see what's using the port.
    - Solution: Stop the conflicting application or choose a different, unused host port for Organizr in your docker-compose.yml.
- Volume Permission Issues (Internal to Container Startup): The user defined by PUID/PGID in docker-compose.yml (which Organizr's internal processes will run as) might not have sufficient permissions to write to or initialize files within the mapped /config volume on first startup or after an update.
  - Diagnosis: Check container logs immediately after a start attempt: docker logs <organizr_container_name>. Look for "permission denied" errors related to creating files/directories in /config, or errors from NGINX/PHP-FPM about being unable to write to log files or sockets.
  - Solution: Ensure the host directory (e.g., ~/my-organizr/data or /opt/organizr/config) is owned by the user/group corresponding to the PUID and PGID specified in your docker-compose.yml. Use sudo chown -R PUID:PGID /path/to/host/config/dir on the host directory before starting the container. For example, if PUID=1000 and PGID=1000, run sudo chown -R 1000:1000 ./data.
- Corrupted Database or Critical Configuration Files: A corrupted SQLite database (organizr.db) or a malformed critical configuration file (e.g., config.php) within the /config volume can prevent NGINX, PHP-FPM, or Organizr's core application from starting correctly.
  - Diagnosis: Container logs are crucial. They might point to a specific file causing a parse error, a database connection failure, or a fatal PHP error during initialization.
  - Solution: If a specific file is identified (and it's not the main database), you might try renaming it (e.g., config.php to config.php.bak) to see if Organizr can regenerate it or start without it (use with caution). If the database is suspected, the primary solution is to restore the entire /config volume from a known good backup.
- NGINX Configuration Errors (Internal to Organizr): If you've added custom NGINX snippets (e.g., in /config/nginx/site-confs/ or /config/nginx/custom-conf.d/) and they contain syntax errors, NGINX will fail to start, and thus the container will likely stop.
  - Diagnosis: Container logs should show NGINX failing to start and often print the exact syntax error, the problematic file, and the line number. You can also try docker exec -it <organizr_container_name> nginx -t if the container stays up long enough to exec into, though this is unlikely if NGINX is failing critically.
  - Solution: Carefully review your custom NGINX configuration file for syntax errors. Correct the errors or temporarily remove/rename the custom file and restart the container to confirm it's the cause.
- PHP Errors (Fatal Errors During Startup): Fatal PHP errors encountered very early in Organizr's bootstrap process can prevent PHP-FPM from running correctly, leading to container failure.
  - Diagnosis: Check PHP-FPM logs (often in /config/log/php/ or similar, accessible via container logs) or general container logs for "PHP Fatal error" messages.
  - Solution: These errors might indicate a problem with a core Organizr file (perhaps due to a bad update or file corruption), a missing or misconfigured PHP extension (unlikely with the official Docker image unless heavily modified), or a severe issue in config.php. Restoring config.php or the entire /config volume from backup is often the quickest fix. If it's a bug in Organizr, you might need to seek community support or report an issue.
- Insufficient System Resources: If the Docker host is extremely low on memory (RAM) or available disk space, Docker might be unable to start new containers or existing ones might be killed by the system's OOM (Out Of Memory) killer.
  - Diagnosis: On the Docker host, check available disk space with df -h and memory with free -m or htop. Docker daemon logs (sudo journalctl -u docker.service) or container logs might sometimes show OOM errors or resource allocation failures.
  - Solution: Free up disk space on the host. Stop non-essential services to free up RAM, or allocate more RAM to the Docker host/VM if it's a virtual machine.
- Incorrect Docker Image Tag or Image Not Found: If you specified a non-existent image tag in your docker-compose.yml (e.g., organizr/organizr:nonexistent-version).
  - Diagnosis: docker compose up will explicitly state "manifest for organizr/organizr:nonexistent-version not found" or similar.
  - Solution: Correct the image tag to a valid one (e.g., organizr/organizr:latest or a specific version number like organizr/organizr:v2.1.900).

4. Homepage Items Not Displaying Data:

Symptom: A configured homepage item (e.g., Sonarr upcoming, SABnzbd queue, Plex recently added) is blank, shows an error message within the widget ("API Key Invalid," "Unable to connect"), or simply doesn't update with new information.
Common Causes & Solutions:
- Incorrect Service URL or API Key: This is the most frequent cause. Even a small typo in the URL (missing http://, wrong port, extra slash) or a single incorrect character in the API key will cause failure.
  - Diagnosis:
    1. In Organizr, go to Settings -> Homepage -> Homepage Items.
    2. Edit the problematic item.
    3. Meticulously double-check the Service URL against how you access the service directly in your browser.
    4. Meticulously double-check the API Key by copying it afresh from the target service's settings (e.g., Sonarr: Settings -> General -> API Key).
  - Solution: Correct any typos or discrepancies in Organizr's homepage item settings and save.
- Network Connectivity/DNS Resolution Failure: The Organizr container must be able to reach the Service URL you provided.
  - Diagnosis:
    1. Get the exact Service URL from Organizr's homepage item settings.
    2. Exec into the Organizr container: docker exec -it <organizr_container_name> /bin/bash (or sh).
    3. Inside the container, try to reach the service:
      - ping <hostname_of_service> (e.g., ping sonarr_server_ip or ping sonarr_container_name if on the same Docker network).
      - curl -v <full_service_url> (e.g., curl -v http://192.168.1.50:8989/api/v3/system/status?apikey=YOUR_API_KEY). The -v (verbose) flag is very helpful to see connection attempts and HTTP headers.
    4. Look for: DNS resolution errors ("Could not resolve host"), connection timeouts, "Connection refused," or HTTP error codes (like 401 Unauthorized, 403 Forbidden, 404 Not Found, 5xx Server Error) from the target service.
  - Solution:
    - Docker Networking: If Organizr and the target service are both Docker containers, ensure they are on the same custom Docker network. This allows them to communicate using container names as hostnames (e.g., http://sonarr:8989). If not on the same network, Organizr needs to use the host's IP and the service's exposed port.
    - Firewall: Check for firewalls on the Docker host or on the machine running the target service that might be blocking connections from Organizr's container IP.
    - DNS for Organizr Container: Ensure the Organizr container has correct DNS servers configured (usually inherited from the Docker host or Docker daemon settings).
- API Disabled or Incorrectly Configured on Target Service: The target service might have its API interface disabled, or the API endpoint Organizr is trying to use might have changed or require specific permissions.
  - Diagnosis:
    1. Log into the target service (e.g., Sonarr, Radarr).
    2. Navigate to its API settings or general settings to ensure the API is enabled.
    3. Check the target service's own logs for any denied API requests from Organizr's IP or any API-related errors.
  - Solution: Enable the API in the target service. Consult the target service's documentation if specific API permissions are needed.
- Rate Limiting by Target Service: If Organizr's homepage item is set to refresh very frequently, the target service might temporarily block or throttle API requests from Organizr, assuming it's abusive.
  - Diagnosis: Check the target service's logs for messages about rate limiting or API abuse from Organizr's IP.
  - Solution: In Organizr's homepage item settings, increase the "Refresh Interval" to a less frequent value (e.g., from 1 minute to 5 or 15 minutes).
- Target Service Not Responding, Erroneous, or Behind Authentication: The target service itself might be down, experiencing internal errors, or require authentication that Organizr isn't providing for that specific API call (though API keys usually handle this).
  - Diagnosis: Try accessing the target service's API endpoint directly in your browser or with curl (using the API key) to see what response it gives. Check the target service's logs.
  - Solution: Resolve the underlying issue with the target service. If it's an authentication issue beyond the API key, the homepage item might not be compatible or might need an update.
- Organizr Application Logs: Check Organizr's main log (Settings -> System -> View Log or docker logs <organizr_container_name>) for any error messages specifically related to fetching homepage item data. These logs might provide more context on why an API call failed from Organizr's perspective.

5. Theme or Customization Issues:

Symptom: Organizr's theme appears broken (e.g., missing styles, weird layout), custom CSS overrides are not applying, or custom uploaded images (logos, favicons) are not loading.
Common Causes & Solutions:
- Corrupted Theme Files or Incomplete Installation: If a custom theme was improperly installed, its files became corrupted, or not all necessary assets were loaded.
  - Solution:
    1. Try switching back to one of Organizr's default themes (e.g., "Default," "Organizr Dark"). If this resolves the issue, the problem lies with the custom theme.
    2. Reinstall the custom theme. Ensure you're getting it from a reliable source.
    3. Try a different custom theme to see if the issue is specific to one theme.
- Browser Cache: Your web browser often caches CSS, JavaScript, and image files to speed up loading. If you've recently changed themes or CSS, the browser might be serving old, cached files.
  - Solution:
    1. Perform a hard refresh in your browser: Ctrl+F5 (Windows/Linux) or Cmd+Shift+R (Mac).
    2. Clear your browser's cache and cookies specifically for your Organizr site.
    3. Test in an incognito/private browsing window, which typically ignores existing cache.
- Incorrect or Conflicting Custom CSS: Syntax errors in your custom CSS, overly broad selectors, or conflicting !important rules can break styling unexpectedly.
  - Diagnosis:
    1. In Organizr (Settings -> Customize -> Custom CSS), temporarily remove or comment out all your custom CSS. Save and see if the issue resolves.
    2. If it does, add back your CSS rules one by one or in small, logical groups, testing after each addition, to pinpoint the problematic rule.
    3. Use your browser's Developer Tools (F12 -> "Elements" or "Inspector" tab). Select the affected element on the page and examine the applied CSS styles. You can see which rules are active, overridden, or invalid. You can also temporarily disable/edit CSS rules directly in the developer tools to experiment.
  - Solution: Correct the faulty CSS syntax. Make your selectors more specific if they are unintentionally affecting other elements. Use !important sparingly and only when necessary.
- File Permissions for Uploaded Images: If custom uploaded logos, favicons, or background images are not displaying (showing a broken image icon), it could be a file permission issue within Organizr's /config volume. NGINX (running inside the Organizr container) needs read permission for these image files.
  - Diagnosis:
    1. Open browser Developer Tools (F12 -> "Network" tab). Refresh the Organizr page. Look for the image request. It might show a 403 Forbidden or 404 Not Found error.
    2. Check NGINX error logs within the Organizr container (docker exec -it <organizr_container_name> cat /config/log/nginx/error.log) for "permission denied" messages when trying to access these image files.
  - Solution: Ensure correct ownership (PUID/PGID) and read permissions for the image files on the Docker host's mapped volume. For example, if your images are in ./config/www/useruploads/, ensure PUID:PGID owns these and they are at least readable by the owner/group (e.g., chmod -R u+rX,g+rX ./config/www/useruploads/).
- Incorrect URL Paths in Theme Files or Custom HTML: If you've manually edited theme files or added custom HTML that references assets (CSS, JS, images) with hardcoded or incorrect paths, they might fail to load, especially if Organizr is behind a reverse proxy or accessed via a subpath.
  - Solution: Whenever possible, use relative paths for assets within a theme or custom HTML. If your theme provides helper functions or variables for generating asset URLs, use them. Ensure paths correctly account for Organizr's base URL.
- Theme Incompatibility with Organizr Version: An older custom theme might not be fully compatible with a newer version of Organizr, leading to visual glitches.
  - Solution: Check if there's an updated version of the theme. If not, you might need to switch to a different theme or attempt to fix the incompatibilities yourself (advanced).

6. Performance Problems (Organizr is Slow):

Symptom: Organizr UI feels sluggish, pages take an unusually long time to load, interactions are delayed.
Common Causes & Solutions:
- Host Server Overloaded: The server (physical or virtual) running the Organizr Docker container might be constrained by CPU, RAM, or slow disk I/O due to other applications or overall system load.
  - Diagnosis: On the Docker host, use system monitoring tools:
    - top or htop: To check CPU utilization and memory usage by process.
    - iotop (install if needed): To check disk I/O activity.
    - free -m: To see detailed memory usage (free, used, buffered/cached).
    - df -h: To check available disk space.
    - vmstat: To see system activity, including swapping.
  - Solution:
    - Identify and reduce the load from other resource-intensive applications on the same host.
    - If the host is consistently overloaded, consider upgrading server hardware (more CPU cores, more RAM, faster SSDs).
    - Optimize other services running on the host.
- Too Many Homepage Items or Very Frequent Refresh Rates: Each enabled homepage item makes API calls to its respective service. Many items, especially those with very short refresh intervals (e.g., every few seconds), can cumulatively add load to Organizr (PHP processing the data) and the target services.
  - Solution:
    - Review your enabled homepage items. Disable any you don't critically need for an at-a-glance view.
    - For enabled items, increase their "Refresh Interval" in Organizr's homepage item settings (e.g., from 1 minute to 5, 10, or 15 minutes, depending on how "live" you need the data).
- PHP Performance Limitations (Less Common for General Slowness): While Organizr's default PHP configuration is usually well-tuned, in very specific scenarios (e.g., extremely complex custom pages or plugins, if Organizr ever supports them more widely), PHP settings like memory_limit or max_execution_time could be a factor if specific operations are timing out or running out of memory.
  - Diagnosis: Check PHP-FPM logs within the Organizr container (e.g., in /config/log/php/) for specific errors like "Allowed memory size exhausted" or "Maximum execution time exceeded." General slowness is less likely to be this unless accompanied by such errors for specific actions.
  - Solution: This is an advanced area. If specific PHP errors indicate resource limits, these might be adjustable via custom PHP-FPM pool configurations or php.ini overrides, but this requires careful changes and understanding of Organizr's internal setup. Consult Organizr documentation or community.
- Database Performance (Especially with SQLite on Large/Busy Instances):
  - If you have a very large number of users, an extensive history of iFramed tabs, many homepage items, and are using the default SQLite database, SQLite's performance might become a bottleneck under heavy load or with very large database files.
  - Diagnosis: This is harder to pinpoint directly without profiling. Symptoms might include slow loading of pages that heavily query the database (like settings pages, user management, tab editor with many tabs).
  - Solution:
    - Organizr may have built-in database optimization routines (like VACUUM for SQLite) or options to clear old history. Check settings.
    - For very large or high-traffic instances, migrating from SQLite to an external MySQL/MariaDB server is a potential (but significantly more complex) solution to improve database concurrency and performance. This is an advanced step.
- Network Latency: If you are accessing Organizr remotely (from outside your local network), general internet connection speed, latency to your server, or issues with your reverse proxy can contribute to perceived slowness.
  - Diagnosis: Test Organizr's speed from within your local network to rule out internet latency. Use ping and traceroute to your Organizr domain to check network path and latency.
- Client-Side Issues: The machine and browser you are using to access Organizr can also be a factor.
  - An old or underpowered computer.
  - An outdated web browser.
  - Many resource-hungry browser extensions running.
  - Solution: Try accessing Organizr from a different, more powerful computer or a different, up-to-date web browser (with extensions disabled or in incognito/private mode) to see if performance improves.

7. Errors After Updating Organizr:

Symptom: After pulling a new Organizr Docker image (e.g., organizr/organizr:latest) and restarting the container, Organizr fails to start, shows new error messages, or exhibits unexpected behavior (broken features, UI glitches).
Common Causes & Solutions:
- Breaking Changes in the New Version: Software development is iterative. New versions can sometimes introduce changes to the database schema, configuration file formats, API endpoints, or dependencies that are not backward-compatible with your existing setup without specific migration steps.
  - Diagnosis: CRITICAL: Always read the release notes for the new Organizr version before updating. Check Organizr's official Docker Hub page (description for the image tag), GitHub releases section, or their official Discord/community forums for announcements, changelogs, and any specific instructions for upgrading.
  - Solution:
    - Follow any migration instructions provided by the Organizr developers precisely.
    - If a critical issue arises and no immediate fix is apparent, your best immediate recourse is often to roll back to the previously working Docker image tag (e.g., if latest was v2.1.900 and you updated, and v2.1.850 was your previous stable version, change your docker-compose.yml to image: organizr/organizr:v2.1.850) AND restore your /config volume from a backup taken before the update.
- Database Schema Migrations: Many web applications, including Organizr, use a database schema. When you update, the new version might need to alter the database structure (add tables, columns, indexes). This migration process usually runs automatically on the first startup after an update.
  - Diagnosis: Container logs during the first startup after an update are key. They might show "Running database migrations," "Updating schema," etc. If this process is interrupted (e.g., you stop the container too soon) or fails, the database can be left in an inconsistent state.
  - Solution: Allow the first startup after an update to complete fully without interruption. If logs indicate migration failure, consult Organizr's support channels. Restoring the pre-update database from backup and retrying the update (after ensuring conditions for success, like sufficient disk space) might be necessary.
- Permissions Changes or Expectations: A new Organizr image might, in rare cases, have slightly different internal user IDs (UID/GID) for its processes or new expectations for file/directory permissions within the /config volume.
  - Diagnosis: Check container logs for permission-denied errors, especially related to files Organizr needs to write (logs, cache, SQLite DB).
  - Solution: Ensure your PUID/PGID in docker-compose.yml are still appropriate and that the host volume permissions for /config are correctly set for these IDs.
- Corrupted Download of the New Docker Image: Though rare, the Docker image download process could be interrupted or result in a corrupted image layer.
  - Solution:
    1. Stop and remove the Organizr container: docker compose down.
    2. Remove the specific Docker image: docker rmi organizr/organizr:<tag_you_used> (e.g., docker rmi organizr/organizr:latest).
    3. Re-pull the image: docker compose pull organizr (or docker pull organizr/organizr:<tag_you_used>).
    4. Start the container again: docker compose up -d.
- Dependency Changes: A new Organizr version might rely on updated versions of PHP, NGINX, or specific libraries. The Docker image handles these internal dependencies, but if there's an incompatibility with your host environment or very old Docker version (unlikely for most users), it could theoretically cause issues.
  - Solution: Ensure your Docker Engine and Docker Compose are reasonably up-to-date.

General Troubleshooting Approach (Recap & Emphasis):

Be Methodical: Don't change multiple things at once. Make one change, test, observe.
Logs, Logs, Logs: This cannot be stressed enough.
- Organizr Container Logs: docker logs <organizr_container_name> or docker compose logs organizr.
- Browser Developer Console (F12): "Console" and "Network" tabs are invaluable.
- Reverse Proxy Logs (NPM, Traefik, etc.): If Organizr is behind one.
- Target Service Logs: If an integration (iFrame, homepage item) is failing.
Isolate the Variable:
- Does the issue occur in all browsers or just one? (Test with incognito/private mode).
- Does it affect all users or a specific user?
- Did the issue start after a specific change (update, new tab, theme change)? Try reverting that change.
Consult Official Resources:
- Organizr Documentation: Check their official website or GitHub wiki.
- Organizr GitHub Issues: See if others have reported similar problems.
- Organizr Discord/Community: Actively maintained communities are excellent for seeking help. Provide clear details of your problem, what you've tried, and relevant log snippets.
Backup Before Risky Fixes: If you're about to try something drastic (e.g., manually editing database files, deleting core config files), ensure you have a recent, verified backup of your Organizr /config volume.

By developing a patient and systematic approach to troubleshooting, leveraging logs effectively, and knowing where to find community support, you can resolve most common Organizr issues and maintain a stable, enjoyable dashboard experience.

Workshop: Basic Organizr Troubleshooting Drills

Goal: To practice common troubleshooting techniques for Organizr by simulating a few typical problems and using logs and browser developer tools to diagnose them.

Prerequisites:

Organizr is installed via Docker Compose and running.
You have at least one iFrame tab and one homepage item configured (even if they are for dummy services for this exercise).
You are comfortable using your browser's developer tools (F12).
You have terminal access to your Docker host to view container logs.

Scenario 1: The Blank iFrame Tab

Problem Simulation: We'll intentionally configure a tab with a URL that blocks iFraming.

Modify a Tab:
- Log into Organizr as admin.
- Go to Settings -> Tabs -> Tab Editor.
- Either edit an existing tab or add a new one.
- Set the Tab URL to https://www.google.com (Google famously blocks iFraming with X-Frame-Options: SAMEORIGIN).
- Ensure Tab Type is "iFrame".
- Give it a name like "Problem Google Tab". Save it.
Observe the Problem:
- Click on your "Problem Google Tab" in Organizr.
- You should see a blank area where Google should load, or sometimes an error message from the browser within the frame.
Diagnose with Browser Developer Tools:
- With the "Problem Google Tab" active in Organizr, open your browser's Developer Tools (press F12).
- Go to the "Console" tab.
- Look for error messages. You should see something like: Refused to display 'https://www.google.com/' in a frame because it set 'X-Frame-Options' to 'SAMEORIGIN'.
- Discussion Point: What does this error message tell you? (Answer: Google's server explicitly instructed the browser not to allow itself to be rendered in an iFrame from a different origin/domain like your Organizr instance.)
Diagnose with Network Tab (Optional but good practice):
- Still in Developer Tools, switch to the "Network" tab.
- You might need to refresh the iFrame (sometimes right-clicking inside the blank iFrame area gives a "Reload frame" option, or re-click the Organizr tab).
- Find the request for www.google.com. Select it.
- Look at the "Headers" sub-tab for this request. Scroll down to the "Response Headers." You should see the x-frame-options: SAMEORIGIN header.
- Discussion Point: How does this confirm the console error? (Answer: It shows the actual HTTP header sent by Google that caused the browser to block rendering.)
Resolve the "Problem":
- Since you can't change Google's server settings, the correct resolution for this type of problem in Organizr is to change the tab type.
- Go back to Settings -> Tabs -> Tab Editor.
- Edit the "Problem Google Tab".
- Change Tab Type from "iFrame" to "External Link".
- Save the tab.
Test the Resolution:
- Click on the "Problem Google Tab" again.
- It should now open Google in a new browser tab/window, which is the expected behavior for an "External Link."

Scenario 2: Homepage Item Fails - "API Key Invalid"

Problem Simulation: We'll configure a Sonarr/Radarr homepage item with an incorrect API key.

Configure a Faulty Homepage Item:
- Ensure you have Sonarr or Radarr running.
- In Organizr, go to Settings -> Homepage -> Homepage Items.
- Add a new item (or edit an existing one) for Sonarr/Radarr.
- Enter the correct Service URL.
- For the API Key, enter a deliberately incorrect key (e.g., 12345abcdef12345).
- Name it "Faulty Sonarr Item" and save.
Observe the Problem:
- Go to your Organizr homepage.
- The "Faulty Sonarr Item" widget will likely show an error message like "Error fetching data," "API Key Invalid," or it might just be blank.
Diagnose with Organizr Logs:
- Open a terminal on your Docker host.
- View the Organizr container logs:
```
docker logs <your_organizr_container_name>
# You might want to tail the logs and then trigger a refresh of the homepage item if possible
# docker logs -f <your_organizr_container_name>
```
- Look for error messages related to the Sonarr/Radarr API. You might see lines indicating an authentication failure, an HTTP 401 or 403 error when trying to connect to Sonarr/Radarr, or messages explicitly mentioning an invalid API key.
- Example (conceptual log output): [Organizr.Api.Sonarr] Error fetching data for 'Faulty Sonarr Item': API call to http://sonarr:8989/api/v3/series failed with status 401 Unauthorized
- Discussion Point: What does the log tell you? (Answer: Organizr tried to connect to Sonarr but was denied access, strongly suggesting an authentication problem like a bad API key.)
Diagnose with Browser Developer Tools (Network Tab):
- On your Organizr homepage, open Developer Tools (F12) and go to the "Network" tab.
- Refresh the Organizr homepage.
- Look for network requests that Organizr makes to fetch data for its homepage items. These might be XHR (XMLHttpRequest) requests to Organizr's own API endpoints, which then make requests to services like Sonarr. Or, in some cases, Organizr might have the browser make direct (proxied) calls.
- If Organizr's backend is making the call, the browser network tab might just show the request to Organizr failing or returning an error that wraps the underlying API issue. The Organizr container logs are often more direct for backend API call failures.
- If you do see a direct call to Sonarr/Radarr (or an Organizr API endpoint that clearly relates to it) that has failed (e.g., with a 401 or 403 status), select it and examine the response.
Resolve the "Problem":
- The diagnosis points to an incorrect API key.
- Go into your Sonarr/Radarr instance, navigate to Settings -> General, and copy the correct API Key.
- In Organizr, go to Settings -> Homepage -> Homepage Items. Edit "Faulty Sonarr Item".
- Paste the correct API key into the API Key field.
- Save the item.
Test the Resolution:
- Go back to your Organizr homepage.
- The "Faulty Sonarr Item" should now load correctly and display data from Sonarr/Radarr.

Scenario 3: Custom CSS Not Applying Correctly

Problem Simulation: We'll add some intentionally "bad" or overly broad CSS.

Add Problematic Custom CSS:

In Organizr, go to Settings -> Customize -> Custom CSS.

Add the following CSS:

/* Intentionally broad and possibly disruptive */
body {
    background-color: limegreen !important; /* Very obvious change */
}

div {
    border: 5px dotted red; /* This will affect many elements */
}

.nonexistent-class-for-testing {
    font-size: 50px; /* This won't do anything, but good to have a non-matching rule */
}

Save Settings.

Observe the Problem:
- Your entire Organizr background might turn lime green.
- Many div elements throughout Organizr will now have a thick red dotted border.
- The "nonexistent-class" rule does nothing visible.
Diagnose with Browser Developer Tools (Elements/Inspector):
- Open Developer Tools (F12) and go to the "Elements" (Chrome) or "Inspector" (Firefox) tab.
- Click the "select element" icon (usually an arrow pointing at a square) in the dev tools toolbar.
- Click on various parts of the Organizr page, for example, the main body area, or a specific div that now has a red border.
- In the "Styles" pane of the developer tools, you will see the CSS rules being applied to the selected element.
  - For the body, you'll see your background-color: limegreen !important; from "inline style sheet" (which is where Organizr injects custom CSS).
  - For a div, you'll see the border: 5px dotted red; rule.
- Discussion Point: How does the Elements/Inspector panel help you see which custom CSS rules are causing the changes? (Answer: It directly shows the source of the applied styles, including your custom CSS, and allows you to temporarily disable them by unchecking them to see the effect.)

Resolve the "Problem":

The diagnosis clearly shows your custom CSS is the cause.
Go back to Settings -> Customize -> Custom CSS.

Remove or comment out the problematic CSS rules:

/* body {
    background-color: limegreen !important;
} */

/* div {
    border: 5px dotted red;
} */

/* .nonexistent-class-for-testing {
    font-size: 50px;
} */

Save Settings.

Test the Resolution:
- Refresh Organizr. The background should revert to normal, and the red dotted borders should disappear.

These drills provide a basic foundation for using key diagnostic tools. Real-world troubleshooting often involves more complex interactions, but the principles of checking logs, using browser developer tools, and isolating variables remain the same.

Personal Dashboard - Organizr

Introduction to Personal Dashboards and Organizr

What is a Personal Dashboard?

Workshop: Conceptualizing Your Ideal Dashboard

Introducing Organizr

Workshop: Exploring the Organizr Demo

1. Basic Setup and Configuration

Prerequisites for Installing Organizr

Workshop: Setting Up Your Docker Environment

Installing Organizr using Docker Compose

Workshop: Your First Organizr Deployment

Initial Organizr Configuration Wizard

Workshop: Completing the Organizr Setup Wizard

Adding Your First Tabs and Services

Workshop: Integrating Your First Two Services

2. Intermediate Customization and Integration

User Management and Permissions

Workshop: Creating User Roles for Family Members

Theming and Appearance Customization

Workshop: Personalizing Your Organizr Look and Feel

Setting Up Homepage Items

Workshop: Integrating Sonarr/Radarr on Your Homepage

Introduction to Reverse Proxies with Organizr

Workshop: Preparing for a Reverse Proxy (Conceptual)

3. Advanced Features and Security

Implementing Single Sign-On (SSO)

Workshop: Setting Up Organizr's Plex SSO for Organizr Login

Securing Organizr with a Reverse Proxy and SSL

Workshop: Securing Organizr with NGINX Proxy Manager and Let's Encrypt

Advanced NGINX Configuration for Organizr

Workshop: Adding a Custom NGINX Location Block for a Simple Internal Page

Backups and Disaster Recovery

Workshop: Performing and Testing a Manual Backup and Restore of Organizr

Troubleshooting Common Organizr Issues

Workshop: Basic Organizr Troubleshooting Drills