Connecting to Komga

Komic is a client for Komga servers. You’ll need a running Komga server with your comics before you can use Komic.

Don’t have a Komga server yet? Visit komga.org for installation instructions. Komga is free, open-source, and runs on Windows, macOS, Linux, or Docker.

First-Time Setup

When you launch Komic, you’ll be guided through connecting to your server:

1. Server URL: The full address of your Komga server

   • Examples: https://komga.example.com or http://192.168.1.100:25600
   • Must include http:// or https://
   • Include the port number if Komga isn’t using standard ports (80/443)

2. Authentication: Choose how to authenticate with your server:

   Username & Password (default):

   • Enter your Komga account username or email
   • Enter your Komga account password

   API Key:

   • Select “API Key” as the authentication type
   • Enter your Komga API key
   • You can generate an API key in Komga’s web interface under “My Account”

Komic will test the connection to verify everything works, then securely save your credentials to iOS Keychain. Your password and API key are encrypted and never stored in plain text.

Extra Headers

Some server configurations require custom HTTP headers for authentication or routing. Common use cases include:

• Reverse proxy authentication (e.g., Authelia, Authentik, Cloudflare Access)
• Custom authentication tokens
• Load balancer configurations

To add extra headers:

1. Tap Advanced Settings during server setup (or edit an existing server)
2. Tap Add Custom Header
3. Enter the header name
4. Enter the header value
5. Repeat for additional headers as needed

These headers are included in all API requests to your server and are stored securely in the iOS Keychain.

Connection Requirements

For local network access (same Wi-Fi):

• http:// works fine for local IP addresses
• Make sure your iPhone/iPad is on the same network as your server

For remote access (over the internet):

• Your server must use HTTPS (not HTTP)
• Apple requires encrypted connections for remote servers
• You’ll need a domain name and SSL certificate for your server

Troubleshooting

Unauthorized

Your credentials are incorrect or expired.

Fix:

• Double-check credentials (usernames are case-sensitive)
• Verify you can log into Komga’s web interface with the same credentials
• Check for accidental spaces in username or password
• If using an API key, verify it hasn’t been revoked in Komga’s settings

Not Found

Komic can’t find the server at that URL.

Fix:

• Verify the URL is correct, including http:// or https://
• Ensure your Komga server is running
• Check the port number if you’re not using defaults
• Try accessing the URL in Safari to confirm it works

Timeout

Komic couldn’t reach the server within 15 seconds.

Fix:

• Check your internet connection
• For local servers, verify you’re on the same Wi-Fi network
• If using VPN, ensure it’s connected and configured correctly
• Check firewall settings on both your device and server
• Try pinging the server from another device to verify network access

SSL Certificate Errors

The server’s SSL certificate couldn’t be validated.

Fix:

• For self-signed certificates, you’ll need to install the certificate on your device
• Or use a proper certificate from Let’s Encrypt or another trusted authority
• For local testing, use http:// with a local IP address instead

Need More Help?

If you’re still having trouble:

• Check Komga’s logs for connection attempts and errors
• Verify Komga’s web interface works in a browser
• Try connecting from another device to isolate the issue
• Reach out on the Komga Discord for community support