Journiv is a self-hosted private journaling application with mood tracking, prompts, analytics, and advanced search.

Yes! All data is stored locally on your server.

Frequently Asked Questions

Name: Journiv
Author: Journiv Team

Common questions about Journiv installation, features, usage, workflows, and best practices.

General Questions

What is Journiv?

Journiv is a self-hosted private journaling application that runs entirely on your own infrastructure. It features mood tracking, prompt-based journaling, media uploads, analytics, advanced search, and more—all while keeping your data completely private and under your control.

Is Journiv free?

Yes! Journiv is free and has an open source core. Optional Journiv Plus addon features are available to Journiv's supporters and helps in Journiv's sustainable development.

Is my data private?

Absolutely! All data is stored locally on your server. Journiv collects zero telemetry, no analytics, and has no external service dependencies. Your journal entries, moods, and media files never leave your infrastructure unless you explicitly export them.

Can I use Journiv offline?

Yes! Once installed, Journiv works completely offline. The Flutter web app (PWA) and mobile apps support full offline functionality with automatic synchronization when connectivity is restored.

What platforms does Journiv support?

Journiv runs on any platform that supports Docker:

Server: Linux, macOS, Windows (with WSL2)
Architecture: AMD64, ARM64, ARMv7 (including Raspberry Pi)
Cloud: AWS, Google Cloud, Azure, DigitalOcean, Hetzner, etc.
Home Lab: Raspberry Pi, Synology NAS, QNAP, TrueNAS, etc.

Installation

What are the system requirements?

Minimum Requirements:

Docker (recommended) or Python 3.9+
512MB RAM (1GB+ recommended)
1GB disk space (more for media files)
Network access for initial setup

Recommended for Production:

2GB+ RAM
10GB+ disk space
PostgreSQL for better performance with large datasets
Reverse proxy (nginx, Traefik, Caddy) for HTTPS

Can I use PostgreSQL instead of SQLite?

Yes! Journiv supports both SQLite (default, perfect for single users) and PostgreSQL (recommended for multiple users or large datasets). Set the DATABASE_URL environment variable to switch to PostgreSQL.

How do I update Journiv?

Docker Compose:

docker compose pull
docker compose up -d

Docker Run:

docker pull swalabtech/journiv-app:latest
docker stop journiv
docker rm journiv
# Run your docker run command again

Important: Always backup your data before updating. Database migrations run automatically on startup.

Can I run Journiv without Docker?

Yes! See the Manual Installation guide for running Journiv directly with Python. This is recommended for development or advanced users who need more control.

Journals and Entries

Can I have multiple journals?

Yes! Create unlimited journals for different purposes—work, travel, personal growth, therapy, etc. Each journal can have custom colors, icons, and separate analytics.

Can I rename a journal?

Yes! Click on the journal name in the journal list, then click the edit icon to rename it. You can also change the color and icon.

How do I schedule an entry for a different date?

When creating or editing an entry, use the Calendar icon in the entry toolbar to adjust the date and time. This is useful for backdating entries or scheduling future entries.

Can I have multiple entries on the same day?

Yes! You can create as many entries as you want on any given day. Each entry has its own timestamp.

How do I add location and weather to an entry?

When creating or editing an entry, click the location icon in the entry toolbar. This opens a bottom sheet where you can:

Adding Location:

Search for a location by typing in the search box
Use your current location by clicking "Use Current Location" (requires location permissions on mobile)
Select a location from the search results

Adding Weather:

First, add a location to your entry (weather requires coordinates)
Once a location is added, click "Fetch Weather" to get current weather conditions for that location
Weather data includes temperature, conditions, and a summary

Both location and weather are optional and can be removed at any time. The location and weather information will appear below your entry content, and you can tap on it to view more details.

Tags and Organization

How do I add tags to an entry?

When creating or editing an entry, use the # icon in the entry toolbar to add tags. Tags are created automatically as you type. Separate multiple tags with commas or press Enter after each tag.

Can I rename or delete tags?

Yes! Go to the tags section in settings or click on a tag to see all entries with that tag. From there, you can rename or delete tags. Deleting a tag removes it from all entries.

How do I see all entries with a tag?

Simply click on any tag to see all entries with that tag. You can also go to the tags page and click on a tag from there to view all entries associated with it.

Should I use tags or separate journals?

Both have their place:

Tags: For cross-cutting themes (e.g., "gratitude", "reflection") that span multiple journals
Journals: For distinct purposes or contexts that you want to keep completely separate

Features

Does Journiv support media uploads?

Yes! You can upload images (JPEG, PNG, GIF, WebP, HEIC), videos (MP4, MOV, WebM), and audio files (MP3, WAV, M4A). Media files are stored locally and automatically generate thumbnails for quick browsing.

What's the maximum file size?

The default maximum is 50MB per file, but this can be configured via the MAX_FILE_SIZE_MB environment variable on your server.

How do I add media to an entry?

When creating or editing an entry, click the media/attachment button and select files from your device. You can upload multiple files per entry.

Can I view media in entries?

Yes! Images display inline, videos can be played directly, and audio files have a built-in player. Media files are stored on your server and accessible only to you.

Can I download media files?

Yes, you can download individual media files from the entry view or export all media as part of a full data export.

Can I search my entries?

Yes! Journiv has powerful full-text search across all entries, tags, and metadata. You can search by:

Entry content (full-text search)
Tags
Date range
Mood
Journal
Location

Does search work offline?

Yes! The mobile apps support offline search. The web app requires connectivity to search entries stored on the server.

Can I save search filters?

Currently, search filters are not saved, but you can bookmark specific filtered views in your browser.

How do I find entries from a specific date?

Use the date range filter in the search/filter options, or navigate to a specific date using the calendar view if available.

Does Journiv have mood tracking?

Yes! Log your mood with timestamps and optional notes. View beautiful visualizations of your mood patterns over time, track streaks, and identify emotional trends.

Can I export my data?

Yes! Journiv supports full data export including all journals, entries, media files, tags, and moods. Exports are provided as ZIP archives that can be imported into another Journiv instance or used for backups.

How do I export my data?

Go to Settings → Export
Choose what to export (all data, specific journals, date range)
Click "Export"
Download the ZIP file when ready

What's included in an export?

Exports include:

All journals and entries
Tags and metadata
Mood data
Media files
User settings (optional)

Can I import data from another Journiv instance?

Yes! Use the Import feature in Settings to upload a Journiv export ZIP file. Your existing data will be preserved, and imported entries will be added.

Can I import from other journaling apps?

Currently, Journiv only supports importing from other Journiv instances. Support for other formats may be added in future releases.

Does Journiv support OIDC/SSO?

Yes! Journiv supports OpenID Connect (OIDC) for Single Sign-On. You can integrate with identity providers like Keycloak, Authentik, Pocket ID, and others. See the Configuration guide for setup instructions.

Mobile Apps

Are there mobile apps?

Yes! Journiv has native Flutter apps for iOS and Android with full offline support, automatic sync, and all features available in the web app.

How do I connect the mobile app to my server?

During login or registration, enter your server URL (e.g., https://journiv.example.com or http://192.168.1.1:8000). The app will validate connectivity and save your server URL for future sessions.

Does the mobile app work offline?

Yes! The mobile apps support full offline functionality. Entries, moods, and media are cached locally and automatically synchronized when connectivity is restored.

How do I sync entries between web and mobile?

Sync happens automatically! When you create or edit entries on mobile, they sync to the server when online. The web app always shows the latest data from the server.

Can I use the mobile app with multiple servers?

Currently, each mobile app installation connects to one server. You can switch servers by logging out and logging in with a different server URL.

How do I clear the mobile app cache?

Go to Settings in the mobile app and look for cache or storage options. Clearing the cache will require re-downloading data on next sync.

Settings and Preferences

How do I change my password?

Go to Settings → Account → Change Password. Enter your current password and choose a new one.

Can I change my username?

Username changes are not currently supported. If you need to change it, you may need to create a new account or contact your administrator.

How do I enable or disable version checking?

Go to Settings → Version and toggle version checking on or off. See the Instance Registration and Updates guide for more details.

Does Journiv collect any data about my instance?

By default, Journiv will collect stats on your installation. This will run after 12 hours to give you time to opt-out. You can opt-out at any time by turning off "Version Checking" from Settings → Version. All data is anonymized and contains no information about your journal entries, filenames, or IP address. The Journiv team actively uses this data to help design the UX and plan new features and enhancements. If you choose to remain opted-in, thank you. It helps in the design and planning effort. Here's an example of the data collected:

{
  "install_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "journiv_version": "0.1.0",
  "platform": "container",
  "db_backend": "postgres"
}

Can I customize the interface?

Interface customization options are limited. You can choose between light and dark themes if available. More customization options may be added in future releases.

Security

How secure is Journiv?

Journiv uses industry-standard security practices:

JWT Authentication: Secure token-based authentication with automatic refresh
Password Hashing: Argon2id for password storage
HTTPS Support: Works behind reverse proxies with SSL/TLS
OIDC/SSO: Optional integration with enterprise identity providers
Input Validation: Comprehensive sanitization and validation
Rate Limiting: Protection against brute force attacks

Can I disable signups?

Yes! Set DISABLE_SIGNUP=true in your environment variables to prevent new user registration. This is useful for private instances or when using OIDC exclusively.

How do I secure my instance?

Best Practices:

Use HTTPS with a reverse proxy (nginx, Traefik, Caddy)
Set a strong SECRET_KEY (generate with openssl rand -base64 32)
Use PostgreSQL with strong passwords
Enable DISABLE_SIGNUP if not needed
Configure firewall rules to restrict access
Keep Journiv updated to the latest version
Regular backups of your data directory

Does Journiv support two-factor authentication (2FA)?

Currently, Journiv relies on OIDC/SSO providers for 2FA. If your identity provider supports 2FA (most do), you can enable it there. Native 2FA support is planned for future releases.

Privacy and Security

Who can see my entries?

Only you! Journiv is self-hosted, so all your data stays on your server. If you're the administrator, only you have access. If you have multiple users, each user can only see their own entries (unless you're an admin viewing all data).

Is my data encrypted?

Data is stored in your database (SQLite or PostgreSQL). For additional security, you can:

Use HTTPS with a reverse proxy
Encrypt your database at the filesystem level
Use encrypted volumes for your Docker containers

Can I use Journiv without internet?

Yes! Once installed, Journiv works completely offline. You only need internet for:

Initial installation and updates
Optional version checking
Mobile app sync (if using remote server)

Does Journiv send my data anywhere?

No! Journiv is completely self-hosted. The only optional external communication is version checking, which only sends version and platform information—never your journal entries or personal data.

Troubleshooting

The container won't start

Check the logs:

docker logs journiv

Common issues:

Missing SECRET_KEY or DOMAIN_NAME environment variables
Port 8000 already in use (change the host port mapping)
Database connection issues (check DATABASE_URL)
Permission issues with the /data volume

I forgot my password

If you're using local authentication:

Create a new account (if signups are enabled)
Or reset via database access (see backend documentation)

If using OIDC, reset your password with your identity provider.

My entries aren't saving

Check:

Internet connectivity (for web app)
Server is running and accessible
Browser console for errors
Try refreshing the page

Media files aren't uploading

Check:

File size limits (MAX_FILE_SIZE_MB environment variable, default 50MB)
Media directory permissions (/data/media must be writable)
Available disk space
Supported file types (images: JPEG, PNG, GIF, WebP, HEIC; videos: MP4, MOV, WebM; audio: MP3, WAV, M4A)

Media files won't upload

Verify:

File size is under the limit (default 50MB)
File type is supported
Server has available disk space
Check server logs for errors

Search is slow

For large datasets:

Switch to PostgreSQL for better performance
Ensure database indexes are created (run migrations)
Consider archiving old entries

Search isn't finding my entries

Try:

Refreshing the page
Checking your search terms
Verifying entries exist in the selected date range
Clearing browser cache

Can't connect mobile app to server

Verify:

Server URL is correct (include http:// or https://)
Server is accessible from your device's network
Firewall allows connections on port 8000 (or your configured port)
CORS is enabled if accessing from a different domain (ENABLE_CORS=true)

Mobile app won't sync

Check:

Server URL is correct
Server is accessible from your device
Internet connectivity
Try logging out and back in
Check server logs for errors

I can't log in

Verify:

Username and password are correct
Server is running
You're using the correct server URL
Check if signups are disabled (contact admin)

Backup & Restore

How do I backup my data?

Docker Compose:

docker compose exec journiv tar czf /data/backup-$(date +%Y%m%d).tar.gz /data
docker compose cp journiv:/data/backup-YYYYMMDD.tar.gz ./backup.tar.gz

Docker Run:

docker exec journiv tar czf /data/backup-$(date +%Y%m%d).tar.gz /data
docker cp journiv:/data/backup-YYYYMMDD.tar.gz ./backup.tar.gz

Or use the export feature in the web UI or API for a portable backup.

How do I restore from backup?

Extract the backup to the /data volume and restart the container. Ensure database migrations are up to date.

How often should I back up my data?

We recommend backing up regularly:

Weekly backups for active users
Before major updates
Before making bulk changes
Use the export feature or automated backup scripts

Best Practices

How should I organize my journals?

Organize based on your needs:

By purpose: Work, Personal, Travel, Therapy
By time period: 2024 Journal, 2025 Journal
By topic: Fitness, Relationships, Career
Create as many journals as you need!

How do I maintain a journaling habit?

Tips:

Set a daily reminder
Start with short entries
Use prompts to get started
Don't worry about perfection
Review your entries periodically to see progress

Support

Where can I get help?

GitHub Issues: Report bugs or request features
Discord: Join our community for real-time help
Reddit: r/Journiv for discussions
Documentation: Comprehensive guides at journiv.com/docs
Email: journiv@protonmail.com

How do I report a bug?

Open an issue on GitHub with:

Description of the issue
Steps to reproduce
Expected vs actual behavior
Logs (if applicable)
Your environment (Docker version, OS, etc.)

Can I contribute?

Absolutely! Contributions are welcome. See CONTRIBUTING.md for guidelines. We welcome:

Bug fixes
Feature additions
Documentation improvements
Translations
Testing and feedback

Getting Started - Learn the basics of using Journiv
Import and Export - Learn how to backup and restore your data
Troubleshooting - Solve common technical issues
Journiv Plus FAQ - Questions about Journiv Plus features and licenses