Portal Desktop Network Share Manager

A cross-platform CustomTkinter desktop application that manages network share mounts using QR code authentication through the member portal.

Features

• QR code authentication via mobile device
• Automatic network share mounting
  • Windows: P: drive
  • macOS: /Volumes/Artifactory
• User information display
• Automatic unmounting on app exit
• Manual disconnect button
• System tray integration

Requirements

Windows

• Windows 10 or later
• Python 3.12 or later
• uv package manager (for dependency management)

macOS

• macOS 10.14 (Mojave) or later
• Python 3.12 or later
• uv package manager (for dependency management)

Installation

1. Install uv (if not already installed)

Windows (PowerShell):

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

macOS/Linux:

curl -LsSf https://astral.sh/uv/install.sh | sh

2. Install dependencies

uv sync

Development

Running the application

uv run python main.py

Test mode (skip network drive mounting)

For testing UI features without access to the file server:

uv run python main.py --test

In test mode, the application will simulate mount/unmount operations without actually accessing the network drive. This is useful for:

• Testing UI components locally
• Development without file server access
• Debugging authentication and user info flows

Building Executables

The build process is cross-platform and automatically detects your operating system.

1. Ensure dependencies are installed

uv sync

2. Build executable

uv run python build.py

For verbose output (recommended for debugging build issues):

uv run python build.py --verbose

3. Output location

Windows:

• Executable: dist/Artifactory Desktop Helper.exe
• Standalone .exe file ready for distribution
• All dependencies are bundled into the single executable

macOS:

• Application bundle: dist/Artifactory Desktop Helper.app
• Drag to /Applications folder to install
• All dependencies are bundled into the .app bundle

Platform-Specific Build Commands

The build script (build.py) automatically detects your platform and uses the appropriate PyInstaller command.

Windows:

uv run pyinstaller --onefile --windowed --icon=icons/icon.ico --add-data "icons;icons" --name="Artifactory Desktop Helper" main.py

macOS:

uv run pyinstaller --onefile --windowed --icon=icons/icon.icns --add-data "icons:icons" --osx-bundle-identifier=au.org.artifactory.desktop --name="Artifactory Desktop Helper" main.py

Configuration

Edit config.json to set the portal base URL:

{
  "portal_base_url": "https://members.artifactory.org.au"
}

Usage

1. Launch the application
2. Click "Generate QR Code"
3. Scan the QR code with your mobile device (must be logged into the portal)
4. Approve the desktop claim on your mobile device
5. The network share will be automatically mounted:
   • Windows: P: drive
   • macOS: /Volumes/Artifactory
6. Your user information will be displayed
7. The mounted share will open automatically in your file manager
8. Use the "Disconnect" button to unmount the share when finished

Network Share Configuration

The network share configuration is stored in the portal's config.json file under the desktop_share section:

{
  "desktop_share": {
    "server": "fileserver",
    "folder": "shares"
  }
}

The share path format is: \\{server}\{folder}\{user_id}

Troubleshooting

PyInstaller build issues

If the build process fails, try:

1. Clean build directories:

   Windows (PowerShell):

   Remove-Item -Recurse -Force build\ -ErrorAction SilentlyContinue
   Remove-Item -Recurse -Force dist\ -ErrorAction SilentlyContinue
   Remove-Item -Force *.spec -ErrorAction SilentlyContinue
   

   macOS/Linux:

   rm -rf build dist *.spec
   

2. Check for missing imports - PyInstaller may miss some imports. If the executable fails to run, check the error message and add hidden imports. (This is unlikely given that we run through uv)

3. Verify the app runs in development mode first:

   uv run python main.py
   

4. Check for antivirus/security interference:

   • Windows: Some antivirus software may interfere with PyInstaller
   • macOS: You may need to allow the app in System Preferences → Security & Privacy

macOS-specific issues

1. "Artifactory Desktop Helper.app is damaged and can't be opened"

   This is a Gatekeeper issue. Remove the quarantine attribute:

   xattr -cr "dist/Artifactory Desktop Helper.app"
   

2. Mount permission errors

   On macOS, mounting network shares may require admin privileges in some cases. The app will prompt for credentials if needed.

QR code expired

The QR code expires after 5 minutes. Click "Generate QR Code" again to create a new one.

Network share mount fails

• Check your network connection - This tool only works when connected to the workshop network
• Verify server configuration - Check the server and folder configuration in the portal config
• Check permissions - Ensure you have access to the network share
• Review logs:
  • Windows: Check Windows Event Viewer for detailed error messages
  • macOS: Check Console.app for mount-related errors

Drive already in use

Windows:

The application will attempt to unmount any existing P: drive before mounting. If this fails, manually unmount:

net use P: /delete

macOS:

If /Volumes/Artifactory is already in use:

umount "/Volumes/Artifactory"