]>
Commit | Line | Data |
---|---|---|
00a48038 TM |
1 | # pve_flutter_frontend |
2 | ||
3 | Frontend for Proxmox Virtual Environment | |
4 | ||
37261111 TL |
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 | ||
0ecfc6cf | 39 | # Run the App |
37261111 | 40 | |
0ecfc6cf | 41 | ## Linux native |
37261111 | 42 | |
db75ae93 TL |
43 | Due to the biometric secret integration you also need libsecret-1: |
44 | ||
45 | apt install libsecret-1-dev | |
46 | ||
37261111 TL |
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 | ||
0ecfc6cf | 59 | ## Build errors |
37261111 TL |
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 | ||
00a48038 TM |
67 | ## Web build infos |
68 | ||
0ecfc6cf TL |
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 | |
9f56e8da | 85 | /usr/bin/chromium --disable-features=CrossOriginOpenerPolicy,CrossOriginEmbedderPolicy --disable-web-security --user-data-dir="/tmp/chrome" $* |
0ecfc6cf TL |
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 | ||
7869e2e8 DM |
94 | $ flutter run -d chrome --web-port=35000 |
95 | ||
96 | ||
352ab963 TL |
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 | ||
0ecfc6cf TL |
101 | ### Use reverse proxy to allow connections to PVE and the App over the same port |
102 | ||
e259af5c TM |
103 | Launch App in Chrome: |
104 | $ flutter run -d chrome --web-port 42000 | |
e259af5c TM |
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 | ||
0ecfc6cf TL |
135 | # Misc. |
136 | ||
e259af5c TM |
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 | ||
0c2b1c5d TM |
146 | var apiClient = await proxclient.authenticate("root@pam", "yourpassword"); |
147 | ||
1e991c53 AL |
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. | |
0c2b1c5d TM |
168 | |
169 | ## Screenshots Android | |
170 | adb shell settings put global sysui_demo_allowed 1 | |
e06fe487 DC |
171 | |
172 | ## Build tooling upgrades | |
173 | ||
174 | In general, updates should be done in the order of: | |
175 | ||
f18f343c TL |
176 | 1. Android Studio |
177 | 2. Flutter | |
178 | 3. Plugins | |
e06fe487 DC |
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 | ||
f18f343c | 186 | ### Upgrade Flutter |
e06fe487 DC |
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 | ||
f18f343c | 195 | ### Upgrade Android Studio |
e06fe487 DC |
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 | ||
f18f343c | 217 | ### Upgrade Kotlin |
e06fe487 DC |
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. |