934 lines
32 KiB
Markdown
934 lines
32 KiB
Markdown
# TASK.md — Current Task: App Detail/Info Pages
|
||
|
||
> Read CLAUDE.md first for project context, workspace layout, and build instructions.
|
||
> This file describes the current task to implement.
|
||
|
||
## Overview
|
||
|
||
Add a dedicated app information page to the felhom-controller dashboard. This page shows detailed
|
||
info about each app (use cases, setup guide, prerequisites) and allows configuring **optional
|
||
settings** (like API keys for metadata providers) both before and after deployment.
|
||
|
||
The first app to get this treatment is **RoMM** (retro game ROM manager), which has optional
|
||
metadata provider API keys (IGDB, SteamGridDB, ScreenScraper, MobyGames).
|
||
|
||
## Architecture context
|
||
|
||
- All HTML/CSS is embedded as Go string constants in `internal/web/templates.go`
|
||
- All UI text is in **Hungarian**
|
||
- Routes are defined in `internal/web/server.go` `ServeHTTP()` method (manual path matching)
|
||
- API routes in `internal/api/router.go` `ServeHTTP()` method
|
||
- App metadata lives in `.felhom.yml` files parsed by `internal/stacks/metadata.go`
|
||
- Per-app deployed config is saved in `app.yaml` (managed by `internal/stacks/deploy.go`)
|
||
- Template functions registered in `server.go` `initTemplates()`
|
||
|
||
## Changes needed
|
||
|
||
This task touches **4 Go files** in the controller + **2 files** in the app-catalog repo.
|
||
|
||
---
|
||
|
||
### 1. `controller/internal/stacks/metadata.go` — Add new structs
|
||
|
||
Add these new fields to the existing `Metadata` struct, and add the new supporting structs:
|
||
|
||
```go
|
||
// Extend the existing Metadata struct with these new fields:
|
||
type Metadata struct {
|
||
// ... all existing fields stay unchanged ...
|
||
DisplayName string `yaml:"display_name" json:"display_name"`
|
||
Description string `yaml:"description" json:"description"`
|
||
Category string `yaml:"category" json:"category"`
|
||
Subdomain string `yaml:"subdomain" json:"subdomain"`
|
||
Slug string `yaml:"slug" json:"slug"`
|
||
Resources ResourceHints `yaml:"resources" json:"resources"`
|
||
DeployFields []DeployField `yaml:"deploy_fields" json:"deploy_fields"`
|
||
|
||
// NEW fields — add these:
|
||
AppInfo AppInfo `yaml:"app_info" json:"app_info"`
|
||
OptionalConfig []OptionalConfigGroup `yaml:"optional_config" json:"optional_config"`
|
||
}
|
||
|
||
// NEW: Detailed app information for the info page
|
||
type AppInfo struct {
|
||
Tagline string `yaml:"tagline" json:"tagline"`
|
||
UseCases []string `yaml:"use_cases" json:"use_cases"`
|
||
FirstSteps []string `yaml:"first_steps" json:"first_steps"`
|
||
Prerequisites []string `yaml:"prerequisites" json:"prerequisites"`
|
||
DefaultCreds string `yaml:"default_creds" json:"default_creds"`
|
||
DocsURL string `yaml:"docs_url" json:"docs_url"`
|
||
}
|
||
|
||
// NEW: Optional config group (e.g., "Metadata providers")
|
||
type OptionalConfigGroup struct {
|
||
Group string `yaml:"group" json:"group"`
|
||
Description string `yaml:"description" json:"description"`
|
||
Fields []OptionalConfigField `yaml:"fields" json:"fields"`
|
||
}
|
||
|
||
// NEW: Individual optional config field
|
||
type OptionalConfigField struct {
|
||
EnvVar string `yaml:"env_var" json:"env_var"`
|
||
Label string `yaml:"label" json:"label"`
|
||
Type string `yaml:"type" json:"type"` // "text" or "secret_input"
|
||
HelpURL string `yaml:"help_url" json:"help_url"`
|
||
HelpText string `yaml:"help_text" json:"help_text"`
|
||
}
|
||
```
|
||
|
||
Add helper methods:
|
||
|
||
```go
|
||
// HasAppInfo returns true if the metadata has any app info content.
|
||
func (m *Metadata) HasAppInfo() bool {
|
||
return m.AppInfo.Tagline != "" || len(m.AppInfo.UseCases) > 0 || len(m.AppInfo.FirstSteps) > 0
|
||
}
|
||
|
||
// HasOptionalConfig returns true if the metadata has any optional config groups.
|
||
func (m *Metadata) HasOptionalConfig() bool {
|
||
return len(m.OptionalConfig) > 0
|
||
}
|
||
```
|
||
|
||
The existing `LoadMetadata()` function uses `yaml.Unmarshal` and will automatically populate the
|
||
new fields if they exist in the YAML. No changes needed to `LoadMetadata()`.
|
||
|
||
---
|
||
|
||
### 2. `controller/internal/stacks/deploy.go` — Add optional config update method
|
||
|
||
Add a new method for updating optional env vars in `app.yaml`. This is safe to call on deployed
|
||
apps — it only touches env vars listed in `optional_config`, never locked fields.
|
||
|
||
```go
|
||
// UpdateOptionalConfig updates optional env vars in app.yaml and restarts the stack if deployed.
|
||
// Only updates env vars that are listed in the metadata's optional_config sections.
|
||
func (m *Manager) UpdateOptionalConfig(stackName string, values map[string]string) error {
|
||
m.mu.Lock()
|
||
defer m.mu.Unlock()
|
||
|
||
stack, ok := m.stacks[stackName]
|
||
if !ok {
|
||
return fmt.Errorf("stack not found: %s", stackName)
|
||
}
|
||
|
||
// Build a set of allowed env vars from optional_config
|
||
allowed := make(map[string]bool)
|
||
for _, group := range stack.Meta.OptionalConfig {
|
||
for _, field := range group.Fields {
|
||
allowed[field.EnvVar] = true
|
||
}
|
||
}
|
||
if len(allowed) == 0 {
|
||
return fmt.Errorf("no optional config fields defined for %s", stackName)
|
||
}
|
||
|
||
// Load existing app.yaml (or create empty one)
|
||
appCfgPath := filepath.Join(m.cfg.Paths.StacksDir, stackName, "app.yaml")
|
||
var appCfg AppConfig
|
||
if data, err := os.ReadFile(appCfgPath); err == nil {
|
||
_ = yaml.Unmarshal(data, &appCfg)
|
||
}
|
||
if appCfg.Env == nil {
|
||
appCfg.Env = make(map[string]string)
|
||
}
|
||
|
||
// Update only allowed env vars
|
||
changed := false
|
||
for key, val := range values {
|
||
if !allowed[key] {
|
||
m.logger.Printf("[WARN] Ignoring non-optional env var: %s", key)
|
||
continue
|
||
}
|
||
if appCfg.Env[key] != val {
|
||
appCfg.Env[key] = val
|
||
changed = true
|
||
m.logger.Printf("[INFO] Updated optional config %s for %s", key, stackName)
|
||
}
|
||
}
|
||
|
||
if !changed {
|
||
return nil
|
||
}
|
||
|
||
// Save app.yaml
|
||
data, err := yaml.Marshal(&appCfg)
|
||
if err != nil {
|
||
return fmt.Errorf("marshal app.yaml: %w", err)
|
||
}
|
||
if err := os.WriteFile(appCfgPath, data, 0600); err != nil {
|
||
return fmt.Errorf("write app.yaml: %w", err)
|
||
}
|
||
m.logger.Printf("[INFO] Saved updated app.yaml for %s", stackName)
|
||
|
||
// If deployed, write .env and restart to pick up new env vars
|
||
if stack.Deployed {
|
||
// Write .env file — reuse the same pattern used by DeployStack
|
||
// Look at how DeployStack writes the .env file and follow the same approach
|
||
if err := m.writeEnvFile(stackName, appCfg.Env); err != nil {
|
||
return fmt.Errorf("write .env: %w", err)
|
||
}
|
||
m.logger.Printf("[INFO] Restarting %s to apply new optional config", stackName)
|
||
// Need to call the internal restart logic (without re-acquiring the lock)
|
||
// Check if there's an unlocked restart method; if not, create one by factoring
|
||
// the restart logic out of RestartStack into a restartStackLocked helper
|
||
if err := m.restartStackLocked(stackName); err != nil {
|
||
return fmt.Errorf("restart after config update: %w", err)
|
||
}
|
||
}
|
||
|
||
return nil
|
||
}
|
||
```
|
||
|
||
**IMPORTANT implementation notes:**
|
||
- Check how `DeployStack` currently writes `.env` files — there's likely a helper that iterates
|
||
`appCfg.Env` and writes `KEY=VALUE` lines. Reuse that exact logic.
|
||
- The existing `RestartStack()` acquires the mutex lock. Since `UpdateOptionalConfig` already
|
||
holds the lock, you need an internal unlocked version. Either:
|
||
- Factor the restart logic out of `RestartStack` into `restartStackLocked` (recommended), or
|
||
- Temporarily release and re-acquire the lock (less clean, avoid if possible)
|
||
- Look at `manager.go` for the restart implementation to understand what needs to be factored out.
|
||
|
||
Also add a public method to load app config (if not already public):
|
||
|
||
```go
|
||
// LoadAppConfig reads app.yaml from a stack directory. Returns nil if not found.
|
||
func (m *Manager) LoadAppConfig(stackName string) (*AppConfig, error) {
|
||
appCfgPath := filepath.Join(m.cfg.Paths.StacksDir, stackName, "app.yaml")
|
||
data, err := os.ReadFile(appCfgPath)
|
||
if err != nil {
|
||
return nil, err
|
||
}
|
||
var cfg AppConfig
|
||
if err := yaml.Unmarshal(data, &cfg); err != nil {
|
||
return nil, err
|
||
}
|
||
return &cfg, nil
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
### 3. `controller/internal/api/router.go` — Add optional config API endpoint
|
||
|
||
Add a new route case in the `ServeHTTP` switch block:
|
||
|
||
```go
|
||
// POST /api/stacks/{name}/optional-config
|
||
case hasSuffix(path, "/optional-config") && req.Method == http.MethodPost:
|
||
r.updateOptionalConfig(w, req, extractName(path, "/optional-config"))
|
||
```
|
||
|
||
And the handler function:
|
||
|
||
```go
|
||
func (r *Router) updateOptionalConfig(w http.ResponseWriter, req *http.Request, name string) {
|
||
r.logger.Printf("[API] Optional config update requested for stack: %s", name)
|
||
|
||
var body struct {
|
||
Values map[string]string `json:"values"`
|
||
}
|
||
if err := json.NewDecoder(req.Body).Decode(&body); err != nil {
|
||
writeJSON(w, http.StatusBadRequest, apiResponse{OK: false, Error: "invalid request body"})
|
||
return
|
||
}
|
||
|
||
if err := r.stackMgr.UpdateOptionalConfig(name, body.Values); err != nil {
|
||
r.logger.Printf("[API] Optional config update failed for %s: %v", name, err)
|
||
writeJSON(w, http.StatusInternalServerError, apiResponse{OK: false, Error: err.Error()})
|
||
return
|
||
}
|
||
|
||
writeJSON(w, http.StatusOK, apiResponse{OK: true, Message: "Beállítások frissítve"})
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
### 4. `controller/internal/web/server.go` — Add info page route and handler
|
||
|
||
#### 4a. The route already exists — update it
|
||
|
||
There's already a case in `ServeHTTP` for `/apps/{slug}`. Currently it redirects to the deploy
|
||
page. Replace the `appDetailHandler` method with a real page handler:
|
||
|
||
```go
|
||
func (s *Server) appDetailHandler(w http.ResponseWriter, r *http.Request, slug string) {
|
||
var found *stacks.StackInfo
|
||
for _, stack := range s.stackMgr.GetStacks() {
|
||
if stack.Meta.Slug == slug {
|
||
found = &stack
|
||
break
|
||
}
|
||
}
|
||
if found == nil {
|
||
http.NotFound(w, r)
|
||
return
|
||
}
|
||
|
||
// Load current optional config values from app.yaml
|
||
currentValues := make(map[string]string)
|
||
if appCfg, err := s.stackMgr.LoadAppConfig(found.Name); err == nil && appCfg != nil {
|
||
for k, v := range appCfg.Env {
|
||
currentValues[k] = v
|
||
}
|
||
}
|
||
|
||
data := s.baseData("stacks", found.Meta.DisplayName)
|
||
data["Stack"] = found
|
||
data["Meta"] = found.Meta
|
||
data["AppInfo"] = found.Meta.AppInfo
|
||
data["OptionalConfig"] = found.Meta.OptionalConfig
|
||
data["CurrentValues"] = currentValues
|
||
data["HasAppInfo"] = found.Meta.HasAppInfo()
|
||
data["HasOptionalConfig"] = found.Meta.HasOptionalConfig()
|
||
|
||
s.render(w, "app_info", data)
|
||
}
|
||
```
|
||
|
||
#### 4b. Add template functions
|
||
|
||
In `initTemplates()`, add to the `funcMap`:
|
||
|
||
```go
|
||
"screenshotURL": func(slug string, index int) string {
|
||
return s.cfg.AppScreenshotURL(slug, index)
|
||
},
|
||
"seq": func(n int) []int {
|
||
result := make([]int, n)
|
||
for i := range result {
|
||
result[i] = i + 1
|
||
}
|
||
return result
|
||
},
|
||
```
|
||
|
||
---
|
||
|
||
### 5. `controller/internal/web/templates.go` — Add info page template + CSS
|
||
|
||
#### 5a. Update `allTemplates` const
|
||
|
||
```go
|
||
const allTemplates = layoutTmpl + dashboardTmpl + stacksTmpl + loginTmpl + logsTmpl + deployTmpl + appInfoTmpl
|
||
```
|
||
|
||
#### 5b. Add `appInfoTmpl` const
|
||
|
||
Design goals: clean layout matching existing dark theme, Hungarian UI, sections for hero header,
|
||
app info cards, screenshots, and optional config form with AJAX save.
|
||
|
||
```go
|
||
const appInfoTmpl = `
|
||
{{define "app_info"}}
|
||
{{template "layout_start" .}}
|
||
|
||
<div class="page-header">
|
||
<div style="display:flex;align-items:center;gap:1rem">
|
||
<a href="/stacks" class="btn btn-sm btn-outline">← Alkalmazások</a>
|
||
<h2>{{.Meta.DisplayName}}</h2>
|
||
</div>
|
||
<div style="display:flex;align-items:center;gap:.5rem">
|
||
{{if .Stack.Deployed}}
|
||
<span class="stack-state-badge state-{{stateColor .Stack.State}}">{{stateLabel .Stack.State}}</span>
|
||
<a href="https://{{.Meta.Subdomain}}.{{.Domain}}" target="_blank" class="btn btn-sm btn-outline">Megnyitás ↗</a>
|
||
<a href="/stacks/{{.Stack.Name}}/logs" class="btn btn-sm btn-outline">Napló</a>
|
||
<a href="/stacks/{{.Stack.Name}}/deploy" class="btn btn-sm btn-outline">Beállítások</a>
|
||
{{else}}
|
||
<a href="/stacks/{{.Stack.Name}}/deploy" class="btn btn-sm btn-primary" onclick="return checkBeforeDeploy(event, '{{.Stack.Name}}')">Telepítés</a>
|
||
{{end}}
|
||
</div>
|
||
</div>
|
||
|
||
<!-- Hero section -->
|
||
<div class="app-info-hero">
|
||
<img class="app-info-logo" src="{{logoURL .Meta.Slug}}"
|
||
alt="{{.Meta.DisplayName}}"
|
||
onerror="this.onerror=function(){this.style.display='none'};this.src='{{logoPNGURL .Meta.Slug}}'">
|
||
<div class="app-info-hero-text">
|
||
{{if .AppInfo.Tagline}}
|
||
<p class="app-info-tagline">{{.AppInfo.Tagline}}</p>
|
||
{{else}}
|
||
<p class="app-info-tagline">{{.Meta.Description}}</p>
|
||
{{end}}
|
||
<div class="stack-meta-badges">
|
||
<span class="meta-badge">~{{.Meta.Resources.MemRequest}} RAM</span>
|
||
<span class="meta-badge">{{.Meta.Category}}</span>
|
||
{{if .Meta.Resources.NeedsHDD}}<span class="meta-badge meta-badge-warn">HDD szükséges</span>{{end}}
|
||
{{if .Meta.Resources.PiCompatible}}<span class="meta-badge meta-badge-ok">Pi kompatibilis</span>{{else}}<span class="meta-badge meta-badge-warn">Csak x86</span>{{end}}
|
||
</div>
|
||
</div>
|
||
</div>
|
||
|
||
<!-- Screenshots (graceful — hidden if assets don't exist) -->
|
||
<div class="app-screenshots" id="screenshots">
|
||
<img src="{{screenshotURL .Meta.Slug 1}}" alt="" class="app-screenshot"
|
||
onerror="this.style.display='none'">
|
||
<img src="{{screenshotURL .Meta.Slug 2}}" alt="" class="app-screenshot"
|
||
onerror="this.style.display='none'">
|
||
<img src="{{screenshotURL .Meta.Slug 3}}" alt="" class="app-screenshot"
|
||
onerror="this.style.display='none'">
|
||
</div>
|
||
|
||
{{if .HasAppInfo}}
|
||
<div class="app-info-grid">
|
||
{{if .AppInfo.UseCases}}
|
||
<div class="app-info-card">
|
||
<h3>🎯 Mire használható?</h3>
|
||
<ul class="app-info-list">
|
||
{{range .AppInfo.UseCases}}<li>{{.}}</li>{{end}}
|
||
</ul>
|
||
</div>
|
||
{{end}}
|
||
|
||
{{if .AppInfo.FirstSteps}}
|
||
<div class="app-info-card">
|
||
<h3>🚀 Első lépések</h3>
|
||
<ol class="app-info-list">
|
||
{{range .AppInfo.FirstSteps}}<li>{{.}}</li>{{end}}
|
||
</ol>
|
||
</div>
|
||
{{end}}
|
||
|
||
{{if .AppInfo.Prerequisites}}
|
||
<div class="app-info-card">
|
||
<h3>📋 Előfeltételek</h3>
|
||
<ul class="app-info-list">
|
||
{{range .AppInfo.Prerequisites}}<li>{{.}}</li>{{end}}
|
||
</ul>
|
||
</div>
|
||
{{end}}
|
||
|
||
{{if .AppInfo.DefaultCreds}}
|
||
<div class="app-info-card">
|
||
<h3>🔑 Alapértelmezett belépés</h3>
|
||
<p class="app-info-creds">{{.AppInfo.DefaultCreds}}</p>
|
||
<p class="app-info-creds-warn">⚠️ Az első bejelentkezés után azonnal változtasd meg!</p>
|
||
</div>
|
||
{{end}}
|
||
|
||
{{if .AppInfo.DocsURL}}
|
||
<div class="app-info-card">
|
||
<h3>📖 Dokumentáció</h3>
|
||
<p><a href="{{.AppInfo.DocsURL}}" target="_blank" class="app-info-link">Hivatalos dokumentáció ↗</a></p>
|
||
</div>
|
||
{{end}}
|
||
</div>
|
||
{{end}}
|
||
|
||
{{if .HasOptionalConfig}}
|
||
<div class="app-optional-config">
|
||
<h3>⚙️ Opcionális beállítások</h3>
|
||
{{range .OptionalConfig}}
|
||
<div class="config-group">
|
||
<h4>{{.Group}}</h4>
|
||
{{if .Description}}<p class="config-group-desc">{{.Description}}</p>{{end}}
|
||
|
||
<div class="config-fields">
|
||
{{range .Fields}}
|
||
<div class="config-field">
|
||
<label for="opt-{{.EnvVar}}">{{.Label}}</label>
|
||
{{if .HelpText}}<p class="config-field-help">{{.HelpText}}</p>{{end}}
|
||
{{if .HelpURL}}<p class="config-field-help"><a href="{{.HelpURL}}" target="_blank">Regisztrációs útmutató ↗</a></p>{{end}}
|
||
<input type="{{if eq .Type "secret_input"}}password{{else}}text{{end}}"
|
||
id="opt-{{.EnvVar}}"
|
||
name="{{.EnvVar}}"
|
||
class="config-input"
|
||
value="{{index $.CurrentValues .EnvVar}}"
|
||
placeholder="{{.Label}}"
|
||
autocomplete="off">
|
||
</div>
|
||
{{end}}
|
||
</div>
|
||
</div>
|
||
{{end}}
|
||
|
||
<div class="config-actions">
|
||
<button class="btn btn-primary" id="save-optional-config" onclick="saveOptionalConfig('{{.Stack.Name}}')">
|
||
Mentés
|
||
</button>
|
||
<span id="config-save-status" class="config-save-status"></span>
|
||
</div>
|
||
</div>
|
||
|
||
<script>
|
||
async function saveOptionalConfig(stackName) {
|
||
const btn = document.getElementById('save-optional-config');
|
||
const status = document.getElementById('config-save-status');
|
||
const inputs = document.querySelectorAll('.config-input');
|
||
|
||
const values = {};
|
||
inputs.forEach(function(input) {
|
||
values[input.name] = input.value;
|
||
});
|
||
|
||
btn.disabled = true;
|
||
btn.textContent = 'Mentés...';
|
||
status.textContent = '';
|
||
status.className = 'config-save-status';
|
||
|
||
try {
|
||
const resp = await fetch('/api/stacks/' + stackName + '/optional-config', {
|
||
method: 'POST',
|
||
headers: {'Content-Type': 'application/json'},
|
||
body: JSON.stringify({values: values})
|
||
});
|
||
const data = await resp.json();
|
||
|
||
if (data.ok) {
|
||
status.textContent = '✓ ' + (data.message || 'Mentve');
|
||
status.className = 'config-save-status config-save-ok';
|
||
} else {
|
||
status.textContent = '✗ ' + (data.error || 'Hiba');
|
||
status.className = 'config-save-status config-save-err';
|
||
}
|
||
} catch(err) {
|
||
status.textContent = '✗ Hálózati hiba';
|
||
status.className = 'config-save-status config-save-err';
|
||
}
|
||
|
||
btn.disabled = false;
|
||
btn.textContent = 'Mentés';
|
||
|
||
setTimeout(function() { status.textContent = ''; }, 5000);
|
||
}
|
||
</script>
|
||
{{end}}
|
||
|
||
{{template "layout_end" .}}
|
||
{{end}}
|
||
`
|
||
```
|
||
|
||
#### 5c. Add CSS to `cssContent`
|
||
|
||
Append these styles at the end of `cssContent` (before the closing backtick):
|
||
|
||
```css
|
||
/* --- App Info Page --- */
|
||
.app-info-hero {
|
||
display: flex;
|
||
align-items: center;
|
||
gap: 1.5rem;
|
||
padding: 1.5rem;
|
||
background: var(--bg-card);
|
||
border-radius: var(--radius);
|
||
border: 1px solid var(--border-color);
|
||
margin-bottom: 1.5rem;
|
||
}
|
||
.app-info-logo {
|
||
width: 80px;
|
||
height: 80px;
|
||
border-radius: 12px;
|
||
object-fit: contain;
|
||
background: var(--bg-secondary);
|
||
padding: 10px;
|
||
flex-shrink: 0;
|
||
}
|
||
.app-info-tagline {
|
||
font-size: 1.1rem;
|
||
color: var(--text-primary);
|
||
margin: 0 0 .75rem 0;
|
||
}
|
||
.app-screenshots {
|
||
display: flex;
|
||
gap: 1rem;
|
||
margin-bottom: 1.5rem;
|
||
overflow-x: auto;
|
||
padding-bottom: .5rem;
|
||
}
|
||
.app-screenshot {
|
||
max-height: 220px;
|
||
border-radius: var(--radius);
|
||
border: 1px solid var(--border-color);
|
||
object-fit: cover;
|
||
}
|
||
.app-info-grid {
|
||
display: grid;
|
||
grid-template-columns: repeat(auto-fill, minmax(300px, 1fr));
|
||
gap: 1rem;
|
||
margin-bottom: 1.5rem;
|
||
}
|
||
.app-info-card {
|
||
background: var(--bg-card);
|
||
border-radius: var(--radius);
|
||
padding: 1.25rem;
|
||
border: 1px solid var(--border-color);
|
||
}
|
||
.app-info-card h3 {
|
||
margin: 0 0 .75rem 0;
|
||
font-size: .95rem;
|
||
color: var(--text-primary);
|
||
}
|
||
.app-info-list {
|
||
margin: 0;
|
||
padding-left: 1.25rem;
|
||
color: var(--text-secondary);
|
||
font-size: .9rem;
|
||
line-height: 1.6;
|
||
}
|
||
.app-info-creds {
|
||
font-family: monospace;
|
||
font-size: 1rem;
|
||
color: var(--accent-light);
|
||
background: var(--bg-secondary);
|
||
padding: .5rem .75rem;
|
||
border-radius: 4px;
|
||
display: inline-block;
|
||
margin: 0 0 .5rem 0;
|
||
}
|
||
.app-info-creds-warn {
|
||
color: var(--orange);
|
||
font-size: .85rem;
|
||
margin: 0;
|
||
}
|
||
.app-info-link {
|
||
color: var(--accent-light);
|
||
text-decoration: none;
|
||
}
|
||
.app-info-link:hover { text-decoration: underline; }
|
||
|
||
/* Optional config section */
|
||
.app-optional-config {
|
||
background: var(--bg-card);
|
||
border-radius: var(--radius);
|
||
padding: 1.5rem;
|
||
border: 1px solid var(--border-color);
|
||
margin-bottom: 1.5rem;
|
||
}
|
||
.app-optional-config h3 {
|
||
margin: 0 0 1rem 0;
|
||
font-size: 1.05rem;
|
||
}
|
||
.config-group {
|
||
margin-bottom: 1.5rem;
|
||
}
|
||
.config-group h4 {
|
||
margin: 0 0 .5rem 0;
|
||
font-size: .95rem;
|
||
color: var(--text-primary);
|
||
}
|
||
.config-group-desc {
|
||
color: var(--text-secondary);
|
||
font-size: .85rem;
|
||
margin: 0 0 1rem 0;
|
||
}
|
||
.config-fields {
|
||
display: grid;
|
||
grid-template-columns: repeat(auto-fill, minmax(320px, 1fr));
|
||
gap: 1rem;
|
||
}
|
||
.config-field {
|
||
display: flex;
|
||
flex-direction: column;
|
||
gap: .25rem;
|
||
}
|
||
.config-field label {
|
||
font-size: .85rem;
|
||
font-weight: 500;
|
||
color: var(--text-primary);
|
||
}
|
||
.config-field-help {
|
||
font-size: .8rem;
|
||
color: var(--text-secondary);
|
||
margin: 0;
|
||
line-height: 1.4;
|
||
}
|
||
.config-field-help a {
|
||
color: var(--accent-light);
|
||
text-decoration: none;
|
||
}
|
||
.config-field-help a:hover { text-decoration: underline; }
|
||
.config-input {
|
||
background: var(--bg-secondary);
|
||
border: 1px solid var(--border-color);
|
||
border-radius: 4px;
|
||
padding: .5rem .75rem;
|
||
color: var(--text-primary);
|
||
font-size: .9rem;
|
||
font-family: monospace;
|
||
width: 100%;
|
||
box-sizing: border-box;
|
||
}
|
||
.config-input:focus {
|
||
outline: none;
|
||
border-color: var(--accent-blue);
|
||
}
|
||
.config-actions {
|
||
display: flex;
|
||
align-items: center;
|
||
gap: 1rem;
|
||
margin-top: 1rem;
|
||
}
|
||
.config-save-status {
|
||
font-size: .9rem;
|
||
transition: opacity .3s;
|
||
}
|
||
.config-save-ok { color: var(--green); }
|
||
.config-save-err { color: var(--red); }
|
||
.meta-badge-warn {
|
||
background: rgba(255, 152, 0, 0.1) !important;
|
||
color: var(--orange) !important;
|
||
}
|
||
.meta-badge-ok {
|
||
background: rgba(76, 175, 80, 0.1) !important;
|
||
color: var(--green) !important;
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
### 6. Update navigation links in `templates.go`
|
||
|
||
#### 6a. Stack cards on Alkalmazások page → link to info page
|
||
|
||
In `stacksTmpl`, the cards currently have `data-href="/stacks/{{.Name}}/deploy"`.
|
||
Change to:
|
||
|
||
```html
|
||
{{if not .Protected}} data-href="/apps/{{.Meta.Slug}}"{{end}}
|
||
```
|
||
|
||
#### 6b. Stack cards on Dashboard → same change
|
||
|
||
Check `dashboardTmpl` for any `data-href` attributes pointing to `/stacks/.../deploy` and update
|
||
them similarly to link to `/apps/{{.Meta.Slug}}` instead.
|
||
|
||
#### 6c. Deploy page → add "Részletek" link
|
||
|
||
In `deployTmpl`, add a link back to the info page near the top header area:
|
||
|
||
```html
|
||
<a href="/apps/{{.Meta.Slug}}" class="btn btn-sm btn-outline">ℹ️ Részletek</a>
|
||
```
|
||
|
||
---
|
||
|
||
### 7. RoMM `.felhom.yml` — Update in app-catalog repo
|
||
|
||
File: `E:\git\app-catalog-felhom.eu\templates\romm\.felhom.yml`
|
||
|
||
Replace the entire file with:
|
||
|
||
```yaml
|
||
# =============================================================================
|
||
# .felhom.yml — App metadata for felhom-controller
|
||
# =============================================================================
|
||
|
||
# --- Display info (shown on dashboard) ---
|
||
display_name: "RomM"
|
||
description: "Retró játékgyűjtemény kezelő"
|
||
category: "media"
|
||
subdomain: "arcade"
|
||
slug: "romm"
|
||
|
||
# --- Resource hints (displayed on deploy screen) ---
|
||
resources:
|
||
mem_request: "300M"
|
||
mem_limit: "1024M"
|
||
pi_compatible: false
|
||
needs_hdd: true
|
||
|
||
# --- Deploy fields (first deployment only) ---
|
||
deploy_fields:
|
||
- env_var: DOMAIN
|
||
label: "Domain"
|
||
type: domain
|
||
description: "A szerver domain neve"
|
||
locked_after_deploy: true
|
||
|
||
- env_var: DB_PASSWORD
|
||
label: "Adatbázis jelszó"
|
||
type: secret
|
||
generate: "password:24"
|
||
locked_after_deploy: true
|
||
|
||
- env_var: MYSQL_ROOT_PASSWORD
|
||
label: "MariaDB root jelszó"
|
||
type: secret
|
||
generate: "password:24"
|
||
locked_after_deploy: true
|
||
|
||
- env_var: ROMM_AUTH_SECRET_KEY
|
||
label: "Hitelesítési titkosítási kulcs"
|
||
type: secret
|
||
generate: "hex:32"
|
||
locked_after_deploy: true
|
||
|
||
- env_var: HDD_PATH
|
||
label: "Adattárolási útvonal"
|
||
type: path
|
||
required: true
|
||
placeholder: "/mnt/hdd_1"
|
||
description: "A külső merevlemez elérési útja, ahol a ROM-ok és borítóképek tárolódnak"
|
||
locked_after_deploy: true
|
||
|
||
# --- App info (info page content) ---
|
||
app_info:
|
||
tagline: "Retró játékgyűjtemény kezelő, böngésző és lejátszó"
|
||
default_creds: "admin / admin"
|
||
docs_url: "https://github.com/rommapp/romm/wiki"
|
||
|
||
use_cases:
|
||
- "Retró játékgyűjtemény rendszerezése és böngészése webes felületen"
|
||
- "Játékok metaadatainak automatikus letöltése — borítók, leírások, értékelések"
|
||
- "Platformonkénti szűrés és keresés a teljes gyűjteményben"
|
||
- "ROM fájlok webes feltöltése és letöltése"
|
||
- "Többfelhasználós hozzáférés a háztartás tagjai számára"
|
||
|
||
first_steps:
|
||
- "Nyisd meg az arcade.DOMAIN címet a böngészőben"
|
||
- "Jelentkezz be az alapértelmezett admin / admin fiókkal"
|
||
- "Változtasd meg azonnal a jelszót a Settings menüben"
|
||
- "Töltsd fel a ROM fájlokat a library mappába (platform/játéknév struktúrával)"
|
||
- "Indíts egy Scan-t a bal oldali menüben a ROM-ok beolvasásához"
|
||
- "Opcionális: állíts be metaadat-szolgáltatókat a borítóképek és leírások automatikus letöltéséhez (lásd lent)"
|
||
|
||
prerequisites:
|
||
- "Külső HDD szükséges a ROM fájlok és borítóképek tárolásához"
|
||
- "Legalább 1 GB szabad RAM ajánlott (MariaDB + Redis + RomM)"
|
||
- "ROM fájlok platform mappákba rendezve (pl. library/gba/, library/snes/)"
|
||
|
||
# --- Optional config (configurable before or after deployment) ---
|
||
optional_config:
|
||
- group: "Metaadat-szolgáltatók"
|
||
description: "Játékok borítóinak, leírásainak és értékeléseinek automatikus letöltéséhez. Legalább az IGDB beállítása ajánlott. Mindegyik ingyenesen használható regisztráció után."
|
||
fields:
|
||
- env_var: IGDB_CLIENT_ID
|
||
label: "IGDB Client ID"
|
||
type: text
|
||
help_url: "https://api-docs.igdb.com/#getting-started"
|
||
help_text: "1) Regisztrálj / jelentkezz be a Twitch fejlesztői portálon (dev.twitch.tv). 2) Hozz létre egy új alkalmazást (bármilyen névvel). 3) Másold be a Client ID-t."
|
||
|
||
- env_var: IGDB_CLIENT_SECRET
|
||
label: "IGDB Client Secret"
|
||
type: secret_input
|
||
help_text: "A Twitch alkalmazásod Client Secret-je (a „New Secret" gombbal generálhatod)."
|
||
|
||
- env_var: STEAMGRIDDB_API_KEY
|
||
label: "SteamGridDB API Key"
|
||
type: text
|
||
help_url: "https://www.steamgriddb.com/profile/preferences/api"
|
||
help_text: "Regisztrálj a SteamGridDB oldalon, majd a Preferences → API fül alatt kattints a „Generate API key" gombra."
|
||
|
||
- env_var: SCREENSCRAPER_USER
|
||
label: "ScreenScraper felhasználónév"
|
||
type: text
|
||
help_url: "https://www.screenscraper.fr/"
|
||
help_text: "Regisztrálj a screenscraper.fr oldalon. A felhasználóneved lesz az API felhasználónév."
|
||
|
||
- env_var: SCREENSCRAPER_PASSWORD
|
||
label: "ScreenScraper jelszó"
|
||
type: secret_input
|
||
help_text: "A screenscraper.fr fiókod jelszava."
|
||
|
||
- env_var: MOBYGAMES_API_KEY
|
||
label: "MobyGames API Key"
|
||
type: text
|
||
help_url: "https://www.mobygames.com/info/api/"
|
||
help_text: "Regisztrálj a MobyGames oldalon, majd az API oldalon igényelj kulcsot. Részletes játékinformációkat és krediteket biztosít."
|
||
```
|
||
|
||
---
|
||
|
||
### 8. RoMM docker-compose.yml template — Add missing env vars
|
||
|
||
File: `E:\git\app-catalog-felhom.eu\templates\romm\docker-compose.yml`
|
||
|
||
In the romm service's `environment:` section, after the existing STEAMGRIDDB line, add:
|
||
|
||
```yaml
|
||
- SCREENSCRAPER_USER=${SCREENSCRAPER_USER:-}
|
||
- SCREENSCRAPER_PASSWORD=${SCREENSCRAPER_PASSWORD:-}
|
||
- MOBYGAMES_API_KEY=${MOBYGAMES_API_KEY:-}
|
||
```
|
||
|
||
---
|
||
|
||
## Implementation order
|
||
|
||
1. `metadata.go` — add structs + helper methods (safe, no side effects)
|
||
2. `deploy.go` — add `UpdateOptionalConfig` + `LoadAppConfig` + factor out restart logic
|
||
3. `router.go` — add `/optional-config` API route + handler
|
||
4. `templates.go` — add `appInfoTmpl`, CSS, update `allTemplates`
|
||
5. `server.go` — replace `appDetailHandler`, add template functions
|
||
6. `templates.go` — update navigation links (stack cards → `/apps/{slug}`, deploy page → "Részletek")
|
||
7. **Commit + push** the controller changes
|
||
8. **Build + push + deploy** the new controller image (see CLAUDE.md for exact commands)
|
||
9. **Verify** the controller starts correctly and the info page renders
|
||
10. Update RoMM `.felhom.yml` in app-catalog repo
|
||
11. Update RoMM `docker-compose.yml` in app-catalog repo
|
||
12. **Commit + push** the app-catalog changes
|
||
13. Trigger catalog sync on demo-felhom (or wait 15m)
|
||
14. **Verify** the RoMM info page shows all sections
|
||
|
||
---
|
||
|
||
## Testing checklist
|
||
|
||
- [ ] `/apps/romm` shows the info page with all sections
|
||
- [ ] Optional config fields display with current values (empty for fresh deployment)
|
||
- [ ] Saving optional config updates `app.yaml` and restarts the stack (if deployed)
|
||
- [ ] Saving optional config on a non-deployed app saves to `app.yaml` without error
|
||
- [ ] Screenshots section hidden gracefully if no assets exist
|
||
- [ ] Stack cards on Alkalmazások page link to `/apps/{slug}`
|
||
- [ ] Deploy page has "Részletek" link back to info page
|
||
- [ ] Apps without `app_info` show minimal info page (header + badges)
|
||
- [ ] Protected stacks (traefik, cloudflared, felhom-controller) not affected
|
||
- [ ] Build succeeds on build server
|
||
- [ ] Controller starts and runs without template parse errors
|
||
- [ ] New version shows in `docker ps`
|
||
|
||
---
|
||
|
||
## Step 15: Update documentation (MANDATORY)
|
||
|
||
After all code changes are done and verified, update these three files:
|
||
|
||
### 15a. `CONTEXT.md`
|
||
|
||
Add a new "What was just completed" section at the top of the history (push down the current
|
||
"What was just completed" to "Previously completed"). Include:
|
||
|
||
- App info/detail pages feature added
|
||
- New `.felhom.yml` fields: `app_info`, `optional_config`
|
||
- New route: `GET /apps/{slug}` renders info page (was redirect to deploy)
|
||
- New API: `POST /api/stacks/{name}/optional-config`
|
||
- RoMM metadata updated with full app_info + 6 metadata provider optional config fields
|
||
- RoMM docker-compose.yml updated with ScreenScraper + MobyGames env vars
|
||
- Navigation: stack cards now link to info page, deploy page has "Részletek" link
|
||
- New controller version: v0.2.11 (or whatever was deployed)
|
||
|
||
Update the "What's next" section — remove items that are done, add any new priorities.
|
||
|
||
### 15b. `controller/README.md`
|
||
|
||
Update to reflect:
|
||
- New `app_info` and `optional_config` sections in `.felhom.yml` format
|
||
- New info page route (`/apps/{slug}`)
|
||
- New API endpoint (`POST /api/stacks/{name}/optional-config`)
|
||
- Add to "What works" list: "App detail/info pages with optional config"
|
||
|
||
### 15c. `CLAUDE.md`
|
||
|
||
Add to the "Key patterns" section:
|
||
- App info pages at `/apps/{slug}` — detail view with use cases, setup guide, optional config
|
||
- Optional config saves to `app.yaml` and restarts deployed apps
|
||
- `optional_config` fields in `.felhom.yml` define post-deploy configurable env vars
|
||
|
||
Add to "Important lessons learned" if any new lessons emerge during implementation.
|
||
|
||
---
|
||
|
||
## Debugging tips
|
||
|
||
- If template fails to parse, the controller crashes on startup with a `template.Must` panic.
|
||
The log output will show the exact parse error (usually missing closing brackets or undefined functions).
|
||
- If `app.yaml` already has deployed config, `UpdateOptionalConfig` merges new values without
|
||
touching locked fields.
|
||
- The `onerror` on screenshot images hides them if assets don't exist — graceful degradation.
|
||
- `config-input` uses `font-family: monospace` intentionally — API keys are easier to verify.
|
||
- The `{{index $.CurrentValues .EnvVar}}` in the template will return empty string for missing
|
||
keys (Go template `index` on map returns zero value) — no nil panic. |