⚙️ Configuration Guide

Set up your GeoServer connection and plugin preferences

⚠️ Security Notice: Password Storage

Important: This plugin was originally developed for internal project use within trusted administrator environments. Credentials (GeoServer and PostGIS passwords) are currently stored in plain text in local configuration files (connection.ini and postgis.ini) for convenience.

Recommendation: Only use this plugin on secure, administrator-controlled computers. Password encryption may be available in future versions. If security is a concern, consider using environment variables or GeoServer's built-in authentication mechanisms.

Opening the Plugin

To open Q2G:

  1. Open QGIS
  2. Go to Plugins → Q2G or click the Q2G icon in the toolbar
  3. The plugin window will open as a docked panel on the right side of QGIS

Q2G Connection Settings

The first step is to configure your Q2G connection. This information is required for all operations.

Required Information

  • GeoServer URL: The base URL of your GeoServer instance
  • Username: Your GeoServer admin username
  • Password: Your GeoServer admin password

Common GeoServer URLs

Setup URL Example
Local Development http://localhost:8080/geoserver
Local with Custom Port http://localhost:9000/geoserver
Remote Server http://geoserver.example.com/geoserver
HTTPS Connection https://geoserver.example.com/geoserver

Entering Connection Details

Step 1: In the Q2G panel, locate the connection settings section at the top
Step 2: Enter your GeoServer URL in the "GeoServer URL" field
Step 3: Enter your username in the "Username" field
Step 4: Enter your password in the "Password" field
Step 5: Click the "Test Connection" button to verify your settings
Success! If the test is successful, you'll see a confirmation message.

Testing Your Connection

Always test your connection before proceeding with uploads:

How to Test

  1. Enter your GeoServer URL, username, and password
  2. Click the "Test Connection" button
  3. Wait for the test to complete

Successful Test

You'll see a message like:

✓ Connection successful! GeoServer version: 2.21.0

Failed Test

If the test fails, you'll see an error message. Common issues:

  • Connection refused: GeoServer is not running or URL is incorrect
  • Authentication failed: Username or password is incorrect
  • Network error: Check your internet connection

Workspace Configuration

After connecting to GeoServer, you need to select or create a workspace.

What is a Workspace?

A workspace is a logical grouping of layers and datastores in GeoServer. Each workspace is independent and can have its own set of layers, styles, and data sources.

Selecting an Existing Workspace

  1. Click the "Workspace" dropdown menu
  2. Select the workspace where you want to upload layers
  3. The plugin will load the workspace's layers and datastores

Creating a New Workspace

  1. Click the "Create New Workspace" button
  2. Enter a name for your workspace (e.g., "my_project")
  3. Click "Create"
  4. The new workspace will be automatically selected
Naming Convention: Use lowercase letters, numbers, and underscores. Avoid spaces and special characters.

Upload Options

Configure how your layers will be uploaded:

Auto-Overwrite Existing Layers

When enabled, the plugin will automatically delete and replace existing layers with the same name:

  • Enabled: Existing layers are replaced (useful for updates)
  • Disabled: Upload fails if layer already exists

Upload SLD Styles

When enabled, the plugin will automatically export and upload QGIS layer styles as SLD:

  • Enabled: Styles are uploaded and applied to layers
  • Disabled: Only layers are uploaded, no styles

Overwrite Existing Styles

When enabled, existing styles on GeoServer will be replaced:

  • Enabled: Existing styles are updated
  • Disabled: Style upload fails if style already exists

Authentication Methods

Basic Authentication (Default)

The plugin uses HTTP Basic Authentication by default:

  • Username and password are sent with each request
  • Recommended for HTTPS connections only
  • Simple and widely supported

HTTPS Connections

For secure connections:

  1. Use https:// in your GeoServer URL
  2. Ensure your GeoServer has a valid SSL certificate
  3. The plugin will handle SSL verification automatically

PostGIS Credentials

For PostGIS layer uploads, you may need to provide database credentials:

  • The plugin will prompt for credentials if needed
  • Credentials are stored locally in postgis.ini
  • You can update them in the PostGIS dialog

Advanced Settings

Proxy Configuration

If you're behind a corporate proxy:

  1. Configure QGIS proxy settings: Settings → Options → Network
  2. The plugin will automatically use these settings

SSL Certificate Verification

For self-signed certificates:

  • The plugin attempts to verify SSL certificates by default
  • For development environments, you may need to disable verification
  • Contact your administrator for proper certificate setup

Timeout Settings

Default timeout values:

  • Connection timeout: 10 seconds
  • Read timeout: 30 seconds
  • Upload timeout: 300 seconds (5 minutes)

Saving Your Settings

Q2G automatically saves your settings:

  • Connection details are saved in QGIS settings
  • PostGIS credentials are saved in postgis.ini
  • Settings persist between QGIS sessions
Security Note: Passwords are stored in QGIS settings. Ensure your QGIS configuration directory has appropriate file permissions.

Troubleshooting Connection Issues

Cannot connect to GeoServer

  • Verify GeoServer is running
  • Check the GeoServer URL is correct
  • Ensure you have network access to the server
  • Check firewall rules

Authentication failed

  • Verify username and password are correct
  • Check if the user has admin privileges
  • Ensure the user hasn't been disabled

Connection timeout

  • Check your internet connection
  • Try increasing the timeout value
  • Check if GeoServer is responding slowly

SSL certificate error

  • Verify the SSL certificate is valid
  • Check the certificate hasn't expired
  • For self-signed certificates, contact your administrator

Next Steps

Once you've configured your connection:

↑