Instance Registration and Updates

Journiv includes optional instance registration and version checking that helps you stay informed about new releases and updates. This guide explains how instance registration works, how version checking operates, and how to manage these features.

What is Instance Registration?

Instance registration is the initial handshake between your Journiv installation and the Journiv Instance Service. It establishes a secure identity for your instance and enables features like version checking. Your instance is registered itself and does a version check approximately 12 hours after you install Journiv to give you time to opt out if you wish.

How It Works

Instance registration uses a Just-In-Time (JIT) registration approach:

• Automatic Registration - Happens automatically when you first use features that require it (like version checking)
• One-Time Process - Registration occurs once per installation
• Secure Identity - Your instance receives a unique secret key (64 hex characters) for authentication
• No Manual Setup - No configuration required, happens transparently in the background

Registration Process

When registration occurs:

1. Check Database - System checks if your instance already has a registration secret
2. Send Registration Request - If not registered, sends a POST request to /api/v1/instance/register
3. Receive Secret - Instance Service returns a unique instance_secret for your installation
4. Store Secret - Secret is saved to your database for future use
5. Authenticate Requests - All future requests use this secret for secure authentication

What Information is Sent During Registration

During registration, your instance sends:

• Install ID - Unique installation identifier (hardware-bound, generated deterministically but not based on your IP address or any other personal identifier)
• Journiv Version - Your current Journiv version number
• Platform - Your operating system/platform (container, bare-metal)
• Database Backend - SQLite or PostgreSQL

Registration Response

The Instance Service responds with:

• Instance Secret - 64-character hexadecimal secret key for authentication
• Status - Registration status confirmation

Privacy and Security

• No Authentication Required - Registration endpoint doesn't require authentication (it's the initial handshake)
• Minimal Data - Only version and platform information is sent
• Secure Storage - Secret is stored securely in your database
• Hardware-Bound - Install ID is tied to your hardware to uniquely identify your installation.

What is Version Checking?

Version checking is an optional feature that periodically checks for new Journiv updates and notifies you when updates are available. It helps you:

• Stay Updated - Know when new versions are released
• Get Security Updates - Be notified of important security patches
• Discover Features - Learn about new features and improvements
• Maintain Compatibility - Ensure your instance is compatible with the latest features

This data also helps the Journiv team understand usage patterns, which we use to improve the user experience and prioritize new features and enhancements. If you choose to remain opted-in, thank you. Your participation directly contributes to making Journiv better.

How It Works

Version checking:

• Requires Registration - Instance must be registered first (happens automatically)
• First Check Delay - The first version check is delayed by 12 hours to give you time to opt out if you wish
• Authenticated Requests - Uses your instance secret to authenticate version check requests
• Connects to Instance Service - Compares your current version with the latest available version
• Shows Notifications - Displays update notifications if a newer version is available
• Provides Links - Includes links to download updates and view changelogs

Privacy and Data

What Information is Sent

When version checking is enabled, your instance sends:

• Current Version - Your Journiv version number
• Install ID - Unique installation identifier (hardware-bound, generated deterministically but not based on your IP address or any other personal identifier)
• Platform - Your operating system/platform
• Database Backend - SQLite or PostgreSQL

What Information is NOT Sent

Version checking does NOT send:

• Your journal entries
• User data or personal information
• Tags, moods, or other content
• Media files
• Server configuration details
• Or any other personal information

Data Usage

The information sent is used only for:

• Version Comparison - Determining if updates are available
• Development Planning - Understanding Journiv's usage and prioritize new features and enhancements.
• Update Notifications - Providing you with update information

Privacy Protection

• Anonymous - No personally identifiable information is sent
• Minimal Data - Only version and platform information
• Optional - You can disable version checking at any time
• Local Processing - Your journal data never leaves your server

Enabling Version Checking

Default Behavior

Version checking is enabled by default, but you can control it through settings. First version checks are delayed by 12 hours to give you time to opt out if you wish. First version check triggers the instance registration process. This is to ensure that you have a chance to opt out if you wish.

How to Enable

1. Log In - Sign in as an administrator
2. Go to Settings - Navigate to Settings → Version
3. Enable Checking - Toggle version checking to "Enabled"
4. Save Settings - Your preference is saved immediately

Automatic Checks

When enabled, version checking:

• Runs automatically in the background
• Checks periodically (typically once per day)
• Shows notifications when updates are available
• Caches results to minimize network requests
• Automatically registers your instance if not already registered

Disabling Version Checking

How to Disable

1. Log In - Sign in as an administrator
2. Go to Settings - Navigate to Settings → Version
3. Disable Checking - Toggle version checking to "Disabled"
4. Save Settings - Version checking stops immediately

After Disabling

When disabled:

• No version checks are performed
• No data is sent to the version checking service
• Update notifications are not shown
• You can still manually check for updates
• If the instance was registered, the registration remains (for future use if re-enabled)

Manual Checks

Even with automatic checking disabled, you can:

• Manually trigger version checks
• View cached version information
• Check for updates on demand

Understanding Update Notifications

Update Available

When a new version is available, you'll see:

• Current Version - Your installed version
• Latest Version - The newest available version
• Update URL - Link to download the update
• Changelog URL - Link to view what's new

No Updates Available

If you're on the latest version:

• Status shows "Up to date"
• No update notifications
• Continue using your current version

Update Information

Update notifications include:

• Version Number - New version identifier
• Release Date - When the version was released
• What's New - Summary of changes
• Download Link - Where to get the update

Network Issues

If version checking fails:

• Cached information is shown
• Error message indicates the issue
• Automatic retry when connectivity returns
• No impact on Journiv functionality

Registration Failures

If registration fails:

• Error is logged for debugging
• Registration will be retried on next attempt
• Version checking will fail gracefully if registration cannot complete
• No impact on core Journiv functionality

Version Check Settings

Viewing Current Status

To view your version check status:

1. Go to Settings - Navigate to Settings → Version
2. View Information - See current version and status
3. Check Details - View last check time and results

Status Information

The version check screen shows:

• Current Version - Your installed Journiv version
• Latest Version - Most recent available version
• Update Available - Whether updates are available
• Last Check - When version was last checked
• Checking Enabled - Whether automatic checking is on

Manual Check

To manually check for updates:

1. Go to Settings - Navigate to Settings → Version
2. Click Check - Click "Check for Updates"
3. View Results - See if updates are available
4. Rate Limits - May be rate limited if checked recently

Frequently Asked Questions

Is Instance Registration Required?

No, instance registration is not required to use Journiv. Instance registration is required for version checking done through the Instance Service. It happens automatically when needed and requires no manual configuration.

When does instance registration happen?

Instance registration happens when:

• Approximately 12 hours after you install Journiv to give you time to opt out if you wish.
• You manually check for updates
• You manually register your instance
• You manually reset your instance registration

Is Version Checking Required?

No, version checking is completely optional. You can disable it at any time.

Does Registration or Version Checking Send My Data?

No, only version and platform information is sent. Your journal entries and personal data are never sent.

Can I Check Versions Manually?

Yes, you can manually check for updates even if automatic checking is disabled.

How Often Are Versions Checked?

When enabled, versions are checked automatically about twice per day.

What If I'm Offline?

Version checking uses cached information when offline and updates when connectivity is restored.

What Happens If Registration Fails?

If registration fails, version checking will not work, but core Journiv functionality is unaffected. Registration will be retried on the next version check attempt.

Can I Reset My Instance Registration?

Instance registration is tied to your installation's Install ID. If you need to reset registration, you would need to reset your Install ID, which is not recommended as it affects other features.

Related Topics

• Getting Started - Learn how to get started with Journiv
• Troubleshooting - Solve common issues