updated CLAUDE.md and TASK.md
This commit is contained in:
@@ -0,0 +1,934 @@
|
||||
# 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.
|
||||
Reference in New Issue
Block a user