Skip to main content

​
Progressive Web App installation

Time Capsule can be installed as a Progressive Web App (PWA) on any device. Once installed, it runs like a native application with offline capabilities, no browser UI, and full desktop integration.

​
Why install as PWA?

Installing Time Capsule as a PWA provides significant benefits over running it in a browser tab:

Offline access

Works completely offline after initial installation. All features remain available without internet

Native experience

Runs in its own window without browser tabs, address bar, or bookmarks toolbar

Desktop integration

Appears in your application launcher, taskbar, and dock alongside native apps

Automatic updates

Service worker automatically downloads updates in the background

Better performance

Static assets cached locally for instant loading and smooth operation

No keyboard conflicts

Avoids browser shortcut conflicts - Ctrl+W cuts text instead of closing tabs

​
Installation methods

Time Capsule displays an installation icon on the desktop when running in a PWA-capable browser.
1

Wait for boot sequence

Open https://debian.com.mx and wait for the system to finish booting. The desktop will appear after the Debian initialization messages complete.
2

Locate the install icon

Look for the “Install PWA” icon on the desktop. It displays a floppy disk image and appears in the top-left corner of the desktop area.
The icon is created by the PWA installer utility at src/scripts/utilities/pwa-installer.ts which listens for the browser’s beforeinstallprompt event.
3

Double-click to install

Double-click the “Install PWA” icon. Your browser will display a native installation prompt.
// The installation triggers this code
export async function installPWA(): Promise<void> {
  await deferredInstallPrompt.prompt();
  const choiceResult = await deferredInstallPrompt.userChoice;
  
  if (choiceResult.outcome === 'accepted') {
    console.log('[PWA] User accepted the install prompt');
  }
}
4

Confirm installation

Click “Install” in your browser’s dialog. The application will be installed and the desktop icon will automatically disappear.
5

Launch the app

Find “Time Capsule” or “Debian CDE” in your application launcher and launch it like any native app.
If the icon doesn’t appear, your browser may not support PWA installation, or Time Capsule may already be installed. Try Method 2 below.

​
Method 2: Browser menu

Most modern browsers offer PWA installation through their menu systems:
1

Look for the install icon

Check the address bar for a small install icon (⊕ or computer icon) on the right side.
2

Click to install

Click the icon and select “Install Time Capsule” from the popup.
3

Alternative: Use menu

If no icon appears, click the three-dot menu (⋮) → “Install Time Capsule” or “Apps” → “Install this site as an app”.
4

Confirm installation

Click “Install” in the dialog that appears.

​
Technical requirements

To install and run Time Capsule as a PWA, you need:

Modern browser

Chrome 73+, Edge 79+, Safari 11.1+, or Firefox 85+ (with limited support)

HTTPS connection

Required for service workers - automatically provided by debian.com.mx

Storage space

~15-20 MB for caching static assets, palettes, and backdrops

JavaScript enabled

Required for PWA functionality and interactive features

​
How it works

Time Capsule’s PWA implementation uses modern web APIs for a native-like experience:

​
Service worker

The service worker (public/sw.js) handles caching and offline functionality: 
// Service worker caching strategy
const STATIC_CACHE = `static-cache-${CACHE_VERSION}`;
const PRECACHE_URLS = ['/', '/css/main.css', '/css/responsive.css'];

// Navigation: network-first with cache fallback
if (request.mode === 'navigate') {
  event.respondWith(
    fetch(request)
      .then((response) => {
        // Cache the response
        caches.open(STATIC_CACHE).then((cache) => 
          cache.put(request, response.clone())
        );
        return response;
      })
      .catch(() => caches.match(request) || caches.match('/'))
  );
}

// Static resources: cache-first strategy
if (url.pathname.startsWith('/css/') || 
    url.pathname.startsWith('/backdrops/') ||
    url.pathname.startsWith('/palettes/')) {
  event.respondWith(
    caches.match(request) || fetch(request)
  );
}

​
Web app manifest

The manifest (public/manifest.webmanifest) defines app metadata: 
{
  "name": "Time Capsule",
  "short_name": "Debian CDE",
  "start_url": "/",
  "display": "standalone",
  "background_color": "#4d648d",
  "theme_color": "#4d648d",
  "description": "A modern Progressive Web App that brings 1990s Unix to any device",
  "icons": [
    {
      "src": "/icons/system/Debian.png",
      "sizes": "192x192",
      "type": "image/png"
    }
  ]
}

​
Offline capabilities

Once installed, Time Capsule works completely offline:
  • Static assets - HTML, CSS, JavaScript cached by service worker
  • Color palettes - All 76 palettes cached locally
  • Backdrops - 168 XPM backdrops cached on demand
  • Virtual filesystem - Stored in IndexedDB, fully offline
  • Application state - Settings and preferences in localStorage
The cache-first strategy for CSS and backdrops means these assets load instantly from local cache, falling back to network only if missing.

​
Verifying installation

After installing, verify Time Capsule is running as a PWA:

​
Check display mode

Time Capsule detects if it’s running as an installed app: 
// Detection code in pwa-installer.ts
if (window.matchMedia('(display-mode: standalone)').matches) {
  console.log('[PWA] Already running as installed app');
  isInstallable = false;
}

​
Visual indicators

When running as a PWA:
  • No browser address bar or navigation controls
  • Own window with system title bar
  • App icon in taskbar/dock
  • “Install PWA” desktop icon no longer appears

​
Browser tools

Check installation in browser developer tools:
  1. Open DevTools (F12)
  2. Go to Application tab (Chrome/Edge) or Storage tab (Firefox)
  3. Check “Service Workers” section - should show “activated and running”
  4. Check “Cache Storage” - should list cached assets

​
Uninstalling the PWA

To remove Time Capsule from your system:
1

Open apps page

Navigate to chrome://apps (Chrome) or edge://apps (Edge) in your browser
2

Find Time Capsule

Locate the Time Capsule or Debian CDE app icon
3

Right-click to uninstall

Right-click the icon and select “Uninstall” or “Remove from Chrome/Edge”
4

Confirm removal

Click “Remove” in the confirmation dialog
Uninstalling removes the app but preserves your data (files, settings) in browser storage. To completely remove all data, also clear site data from browser settings.

​
Troubleshooting

Possible causes:
  • Browser doesn’t support PWA installation
  • Time Capsule is already installed
  • Page not served over HTTPS (shouldn’t happen on debian.com.mx)
  • Browser extensions blocking installation prompts
Solutions:
  • Try Method 2 (browser menu installation)
  • Check if the app is already installed
  • Disable browser extensions temporarily
  • Try a different browser (Chrome/Edge recommended)
  • Refresh the page and wait for full boot completion
Possible causes:
  • Insufficient storage space
  • Browser cache corrupted
  • Service worker registration failed
Solutions:
  • Free up disk space (need ~20 MB)
  • Clear browser cache and site data
  • Check browser console for specific errors
  • Try incognito/private mode first
  • Restart your browser
Possible causes:
  • Service worker not activated
  • Cache not fully populated
  • Browser cleared cache
Solutions:
  • Visit all sections while online first to populate cache
  • Check service worker status in DevTools Application tab
  • Reinstall the PWA to refresh cache
  • Wait a few minutes after installation for background caching
// Verify service worker in console
navigator.serviceWorker.getRegistration().then(reg => {
  console.log('Service Worker:', reg.active.state);
});
Issue: Shortcuts like Ctrl+W (cut in XEmacs) close browser tabs instead.Solution: This confirms you’re NOT running as PWA. Install as PWA (standalone mode) to eliminate browser conflicts. In standalone mode, Time Capsule controls all keyboard shortcuts.
How updates work: Service worker checks for updates automatically. When found, it downloads in background and activates on next launch.Force update:
  • Close all Time Capsule windows/tabs
  • Clear service worker: DevTools → Application → Service Workers → Unregister
  • Reload the page
  • New version will install
The service worker version is tied to package.json version number and updates automatically when changed.
Platform-specific:
  • Windows: Check Start Menu under recently added
  • macOS: Look in Applications folder or Launchpad
  • Linux: Check application menu (varies by DE)
  • iOS/iPadOS: Check all home screens
Alternative: Create a bookmark/shortcut to https://debian.com.mx and add it to your desktop or taskbar as a workaround.

​
Platform-specific notes

​
Windows

  • Best experience with Chrome or Edge
  • App appears in Start Menu under recently added
  • Can be pinned to taskbar
  • Window has native Windows title bar

​
macOS

  • Chrome/Edge recommended (Safari has limitations)
  • App appears in Applications folder
  • Can be added to Dock
  • Follows macOS window management conventions

​
Linux

  • Chrome/Chromium recommended
  • App integrates with desktop environment
  • Appears in application menu (GNOME, KDE, etc.)
  • Respects system theme for window decorations

​
iOS/iPadOS

  • Safari is the only option
  • Touch gestures work perfectly
  • Can be added to home screen
  • Runs in fullscreen when launched
  • Note: Limited offline capabilities due to Safari PWA restrictions

​
Android

  • Chrome recommended
  • Excellent PWA support
  • Add to home screen feature
  • Full offline functionality
  • Can use back button for navigation

​
Best practices

Install on all devices

Install on desktop for productivity and mobile for on-the-go access

Allow background updates

Keep Time Capsule in your app list for automatic updates

Use standalone mode

Always launch from app icon, not browser bookmark

Cache content first

Explore all sections while online to cache everything

​
Next steps

Now that Time Capsule is installed:

Quickstart guide

Learn the essential features in 5 minutes

Keyboard shortcuts

Master the 20+ shortcuts for power users

Terminal Lab

Complete all 22 Unix/Linux lessons

Customize themes

Explore 76 palettes and 168 backdrops
For the best experience, install Time Capsule on both your desktop (for productivity) and mobile device (for showing friends). The offline support means it works everywhere!