README.md

   1 # pve_flutter_frontend
   2
   3 Frontend for Proxmox Virtual Environment
   4
   5 # Setup How-To
   6
   7 ## Get Flutter
   8
   9 See:
  10 https://flutter.dev/docs/get-started/install/linux#install-flutter-manually
  11
  12 Make `flutter doctor` as happy as possible. Note you may need to tell it where
  13 chromium is located, e.g., with `export CHROME_EXECUTABLE=/usr/bin/chromium`
  14
  15 ## Get Path-Dependencies
  16
  17 Most dependencies can be served from pub.dev, but the frontend also depends on
  18 to local path dependencies maintained by Proxmox.
  19
  20 So, in the parent folder clone both, the API client library (pure dart package)
  21 and the login manager, serving as a base for Proxmox api2 projects.
  22
  23  cd ..
  24  git clone git://git.proxmox.com/git/flutter/proxmox_dart_api_client.git
  25  cd proxmox_dart_api_client
  26  flutter pub get
  27  flutter packages pub run build_runner build --delete-conflicting-outputs
  28
  29
  30  cd ..
  31  git clone git://git.proxmox.com/git/flutter/proxmox_login_manager.git
  32  cd proxmox_login_manager
  33  flutter pub get
  34  flutter packages pub run build_runner build --delete-conflicting-outputs
  35
  36 Now you have made the local dependencies and their dependencies available, and
  37 built the generated (data) model code for each.
  38
  39 # Run the App
  40
  41 ## Linux native
  42
  43 Due to the biometric secret integration you also need libsecret-1:
  44
  45  apt install libsecret-1-dev
  46
  47 With the dependencies setup you should cd back into this directory
  48 (pve_flutter_frontend repository root) and also generate the model code once:
  49
  50  flutter packages pub run build_runner build --delete-conflicting-outputs
  51
  52 Note: the `--delete-conflicting-outputs` option is normally not required, but
  53 can come in handy during development trial/error coding.
  54
  55 To actually run it you can do:
  56
  57  flutter run -d linux
  58
  59 ## Build errors
  60
  61 If there's an error during build use the verbose `-v` flag, to make flutter
  62 tell you what's actually going on. Quick remedies are then often rebuilding the
  63 models, build from clean state, upgrade or downgrade flutter to the last known
  64 working version - as we use latest master we sometimes run actually into bugs.
  65 Or if you made code changes resulting in an error, well duh, fix those.
  66
  67 ## Web build infos
  68
  69 You'll need some sort workaround for CORS in order to serve the flutter
  70 frontend from your local dev machine, which will enable some convenient
  71 features, like hot reload, automatic builds on changes...
  72
  73 This is required as CORS boundaries are any change in <scheme><addr><port>
  74 tuples, and chrome will forbid even cross site requests to localhost on a
  75 different port.
  76
  77 ### Disable CORS in chrome/ium
  78
  79
  80 Create a small shell script, lets name it `chrome-no-cors.sh`, with the
  81 following content:
  82
  83     #!/bin/sh
  84     mkdir -p /tmp/chrome || true
  85     /usr/bin/chromium --disable-features=CrossOriginOpenerPolicy,CrossOriginEmbedderPolicy --disable-web-security --user-data-dir="/tmp/chrome" $*
  86
  87 Then `chmod +x chrome-no-cors.sh` it and adapt the CHROME_EXECUTABLE env
  88 variable:
  89
  90      export CHROME_EXECUTABLE="$(realpath chrome-no-cors.sh)"
  91
  92 Now you can start the web based build normally:
  93
  94 $ flutter run -d chrome --web-port=35000
  95
  96
  97 NOTE: without setting a fixed port flutter uses a random one, as chrome binds
  98  certificate expections and local browser storage to a (protocol, host, port)
  99  tuple, this means that we'd lose all saved settings etc. every time else
 100
 101 ### Use reverse proxy to allow connections to PVE and the App over the same port
 102
 103 Launch App in Chrome:
 104 $ flutter run -d chrome --web-port 42000
 105
 106 nginx snippets:
 107
 108 location / {
 109
 110         if ( $query_string ~ "console" ) {
 111                 proxy_pass https://<clusterip>:8006;
 112         }
 113         proxy_pass http://127.0.0.1:42000;
 114         proxy_read_timeout 24h;
 115         proxy_http_version 1.1;
 116         proxy_set_header Connection "";
 117         proxy_buffering off;
 118
 119 }
 120
 121 location /xterm {
 122         proxy_set_header Host $host;
 123         proxy_set_header Cookie $http_cookie;
 124         proxy_pass https://<clusterip>:8006;
 125 }
 126
 127 location /api2 {
 128         proxy_set_header Upgrade $http_upgrade;
 129         proxy_set_header Connection "Upgrade";
 130         proxy_set_header Host $host;
 131         proxy_set_header Cookie $http_cookie;
 132         proxy_pass https://<clusterip>:8006;
 133 }
 134
 135 # Misc.
 136
 137 To upgrade the proxmox_api_client dependency execute:
 138 $ flutter packages upgrade
 139
 140 To build the model classes use:
 141 $ flutter packages pub run build_runner build
 142
 143 If you want to login without typing your password for your
 144 Test-Cluster, add this to the main function:
 145
 146 var apiClient = await proxclient.authenticate("root@pam", "yourpassword");
 147
 148 ## Android vector drawables
 149
 150 Android does support vector drawables, but not SVGs directly. They need to be
 151 converted to the Android specific subset of SVG and are stored as xml files.
 152
 153 One way to do that is to use the Asset Studio which is part of Android Studio.
 154 In your (dummy) project, right click in the tree view on
 155 app -> New -> Vector Asset.
 156
 157 There are other options, but they have some caveats themselves.
 158
 159  * a web service which is subscription based https://svg2vector.com/
 160  * a JS based CLI tool, but it is npm based... https://github.com/Ashung/svg2vectordrawable
 161
 162 ## Android splash screen logo
 163
 164 Will be masked, see figure 2 in https://developer.android.com/guide/topics/ui/splash-screen
 165 The drawable therefore needs to account for that by being quite a bit bigger.
 166 The `assets/images/android_launch_background_template.svg` file is useful to
 167 size the logo / icon accordingly.
 168
 169 ## Screenshots Android
 170 adb shell settings put global sysui_demo_allowed 1
 171
 172 ## Build tooling upgrades
 173
 174 In general, updates should be done in the order of:
 175
 176 1. Android Studio
 177 2. Flutter
 178 3. Plugins
 179
 180 and then select a gradle and android gradle plugin version which are compatible
 181 with each other and the other parts.
 182
 183 To do this correctly, it's necessary to check the respective release notes
 184 and compatibility tables/matrices.
 185
 186 ### Upgrade Flutter
 187
 188 to upgrade flutter itself, just run
 189
 190  flutter upgrade
 191
 192 check https://docs.flutter.dev/release/release-notes for breaking changes
 193 and migration information
 194
 195 ### Upgrade Android Studio
 196
 197 Depends on the method you installed, on Linux with tarballs, normally
 198 the new version is downloaded/extracted again, and it will automatically
 199 detect & migrate old settings and configuration files on first start.
 200
 201 The Android Studio version determines which Gradle/AGP version you can use.
 202 Check the respective release notes for Gradle/AGP versions:
 203 https://developer.android.com/studio/releases
 204
 205 ### Gradle/Android Gradle Plugin (AGP)
 206
 207 Compatibility depends on the Android Studio, Flutter and plugins.
 208 Can be changed in Android Studio under
 209 File -> Project Structure -> Project
 210
 211 When selected, Android Studio will automatically download/build them, and
 212 change the entries in the android/build.gradle file.
 213
 214 See https://developer.android.com/build/releases/gradle-plugin for
 215 AGP/Gradle compatibility.
 216
 217 ### Upgrade Kotlin
 218
 219 Compatibility depends on Flutter plugins and Gradle, check
 220 https://docs.gradle.org/current/userguide/compatibility.html
 221
 222 To change the used kotlin version, edit it in the android/build.gradle file
 223 manually.