WebGUI
Warning
The WebGUI is currently in BETA status
Open a bug report or feature request in versitygw Issues for any bugs or new feature requests
The WebGUI is NOT enabled by default. The listening port must be configured in order to enable the WebGUI.
This guide covers the configuration, authentication, and usage of the VersityGW WebGUI interface. Admin users will have access to additional management features, while standard users can manage their buckets and objects through the Explorer interface.
--webui value enable WebUI server on the specified listen address (e.g. ':7071', '127.0.0.1:7071', 'localhost:7071'; disabled when omitted) [$VGW_WEBUI_PORT]
--webui-cert value TLS cert file for WebUI (defaults to --cert value when WebUI is enabled) [$VGW_WEBUI_CERT]
--webui-key value TLS key file for WebUI (defaults to --key value when WebUI is enabled) [$VGW_WEBUI_KEY]
--webui-no-tls disable TLS for WebUI even if TLS is configured for the gateway (default: false) [$VGW_WEBUI_NO_TLS]
The --webui option takes a :<port> or <ip/name>:<port> style option to specify listening interface/port for the webui. For example, if I want to enable the webui on port 7071, I could run the following:
versitygw --access test --secret test --iam-dir /tmp/gw --webui :7071 posix --versioning-dir /tmp/vers /tmp/gw
Note
The WebGUI requires CORS Access-Control-Allow-Origin headers to be enabled.
If --cors-allow-origin <url> is not specifically set, then enabling --webui <port> will automatically enable --cors-allow-origin *
The CORS Access-Control-Allow-Origin headers must be set to the s3 endpoint URL or the wildcard (*).
Once the WebGUI is enabled and the gateway is running, you can access the interface through your web browser.
To access the WebGUI, navigate to the URL specified in your port configuration in a web browser. For example, if using the configuration shown above, visit http://127.0.0.1:7071.
The login page allows you to authenticate using your access and secret key credentials. Advanced options are available to specify alternative S3 or admin endpoints if your gateway is configured with custom endpoints. By default, the WebGUI uses the endpoints from the gateway hosting the interface.
To logout after you're finished, click the "Sign Out" button in the bottom left corner of the interface.
After logging in, the interface you see will depend on your account role. Admin accounts have access to the Dashboard, Users, and Buckets management pages, plus full access to the Explorer view for all buckets. Standard user accounts are limited to the Explorer view and can only see buckets they own.
The following sections describe features available to admin role accounts. If you're using a standard user account, skip ahead to the Explorer section.
The Admin Dashboard is only enabled when an IAM service is defined. If the gateway is running in single user mode with no IAM service, then the admin login will be treated as a normal user since there are no accounts to manage. For this case skip down to user explorer documentation.
The Dashboard is the initial landing page after logging in with an admin account. It provides an overview of gateway status, including:
- Gateway health and uptime
- Total number of users
- Total number of buckets
- System statistics and metrics
The left navigation menu provides access to all WebGUI functionality. Note that Dashboard, Users, and Buckets pages are only visible to admin role accounts.
The Users page provides comprehensive account management capabilities. From this interface, you can:
- View all user accounts in a searchable table
- Create new user accounts with customizable credentials
- Modify existing user properties and roles
- Delete user accounts when needed
Click the + Create User button to open the user creation dialog. You can configure:
- Access Key: Enter manually or click "Generate" for an automatic key
- Secret Key: Enter manually or click "Generate" for an automatic key
- Role: Select from the dropdown (admin, user, or userplus)
- Advanced Options: Optionally set uid/gid/projectid when these backend features are enabled
The Buckets page provides administrative bucket management capabilities. From this interface, admins can:
- View all buckets across all users
- Change bucket ownership by reassigning to different accounts
- Create new buckets and assign them to specific users
The Explorer page is the primary interface for browsing and managing bucket contents. This view is available to both admin and standard user accounts, with the key difference being scope:
- Admin accounts: Can view and manage all buckets across all users
- User accounts: Can only view and manage buckets they own
For detailed Explorer functionality, see the Explorer section below.
The Explorer is the primary workspace for managing buckets and objects. Both admin and standard users have access to this interface, though the buckets visible depend on your account role.
The Explorer page at the top level displays a table of buckets accessible to your account (buckets you own for standard users, or all buckets for admin accounts). The bucket table includes:
- Name: The bucket identifier
- Versioning: Current versioning status (Enabled/Suspended)
- Object Lock: Object lock configuration status (Enabled/Disabled)
- Created: Bucket creation timestamp
- Actions: Quick access icons for bucket management
The following action icons are available for each bucket:
- Info - Display bucket information and tags; set or modify bucket tags
- Policy Manager - View and edit the bucket policy
- Versioning - Enable or suspend bucket versioning
- Object Lock - Enable or update object lock configuration
- Multipart Uploads - View and manage outstanding multipart uploads
- Delete Bucket - Delete the bucket (only available when bucket is empty)
Clicking on a bucket name opens the object explorer, which provides a folder-based hierarchical view of the bucket contents. Within this view, you can:
- Create new folders to organize objects
- Upload objects via drag-and-drop or file selector
- Download objects to your local system
- Navigate through folder structures
- Manage object versions when versioning is enabled
The object explorer table displays the following information for each object:
-
Name - The object name (last component in the path). For example, object
dir1/dir2/fileis shown as "file" within the dir1/dir2/ folder - Versions - Version count (appears when multiple versions exist); click to list/download/delete specific versions
- Size - Object size in human-readable format
- Modified - Last modification timestamp
- Class - Storage class for the object (e.g., STANDARD, GLACIER)
-
Actions - Quick access icons:
- Versions - Versions (if multiple versions exist); click to list/download/delete specific versions
- Info - View detailed object information; set or modify tags and metadata
- Download - Download the object to your local system
- Delete - Delete the object or specific version
