Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
10 changes: 9 additions & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -141,7 +141,15 @@ make lint
make app # the macOS app, into build/macos/Flock.app
```

The Windows app is described in [windows/README.md](windows/README.md). On Linux, `linux/build-packages.sh` builds the CLI and the app into `.deb` and `.rpm` packages (it needs Rust and the GTK 4, libadwaita and WebKitGTK 6 development packages).
The Windows app is described in [windows/README.md](windows/README.md). On Linux, the app needs Rust and the GTK 4, libadwaita and WebKitGTK 6 development packages. To build, test and open it from the repository root:

```sh
cargo build --locked --manifest-path linux/Cargo.toml
cargo test --locked --manifest-path linux/Cargo.toml
cargo run --locked --manifest-path linux/Cargo.toml
```

The app can open without the daemon, but needs Flock set up to use its services. `linux/build-packages.sh` builds the CLI and the app into `.deb` and `.rpm` packages.

## Contributing

Expand Down
10 changes: 10 additions & 0 deletions docs/cli.md
Original file line number Diff line number Diff line change
Expand Up @@ -24,6 +24,7 @@ This page lists the `flock` commands. The other pages show where to find each ac

| Command | Description |
| --- | --- |
| `flock app create <name> [--type <template>] [--db] [--db-service <service>] [--php 8.4] [--secure]` | Create a project from a template in a new subdirectory and link it as `<name>.test` |
| `flock park [dir]` | Serve every subdirectory of `dir` as `<subdir>.test` |
| `flock unpark [dir]` | Stop serving a parked directory (alias: `forget`) |
| `flock link [name] [--php 8.4] [--secure]` | Serve the current directory as `<name>.test` |
Expand All @@ -49,6 +50,15 @@ This page lists the `flock` commands. The other pages show where to find each ac
| `flock share [name] [--allow <email>] [--debug]` | Share a site at a temporary public URL until you press <kbd>Ctrl</kbd>+<kbd>C</kbd> |
| `flock share [name] --stop` | Stop sharing a site (e.g. one shared from the app) |

### Creating an application

```sh
flock app create my-app
flock app create my-blog --type wordpress
```

Creates a project in `<name>` from a template (`blank`, `php`, or `wordpress`; default `php`) and links it as `<name>.test`. Add or override templates in `apps.conf` inside Flock's data directory (`%AppData%\Flock` on Windows, `~/.local/share/flock` on Linux, `~/Library/Application Support/Flock` on macOS). Templates marked with `| db` (such as `wordpress`) and `--db` require running MySQL or MariaDB, create a matching database (and fill `wp-config.php` from `wp-config-sample.php`), and `--db-service` selects a specific one. Existing folders, sites, and proxies are never overwritten.

## PHP & Node.js

| Command | Description |
Expand Down
1 change: 1 addition & 0 deletions internal/api/api.go
Original file line number Diff line number Diff line change
Expand Up @@ -360,6 +360,7 @@ func NewHandler(b Backend, token string) http.Handler {
})

registerConfig(mux, b)
registerApps(mux, b)
registerPHPVersions(mux, b)
registerExtensions(mux, b)
registerNodeVersions(mux, b)
Expand Down
84 changes: 84 additions & 0 deletions internal/api/appsapi.go
Original file line number Diff line number Diff line change
@@ -0,0 +1,84 @@
package api

import (
"context"
"errors"
"net/http"
"path/filepath"

"flock/internal/apps"
"flock/internal/config"
)

// AppsDatabases maps daemon services into the database descriptors apps.Create expects.
func AppsDatabases(services []Service) []apps.Database {
out := make([]apps.Database, len(services))
for i, s := range services {
out[i] = apps.Database{
ID: s.ID, Name: s.Name, Version: s.Version, Port: s.Port,
Installed: s.Installed, Running: s.Running,
}
}
return out
}

func registerApps(mux *http.ServeMux, b Backend) {
mux.HandleFunc("GET /v1/apps/templates", func(w http.ResponseWriter, _ *http.Request) {
templates, err := apps.Load(b.Root())
if err != nil {
writeError(w, http.StatusInternalServerError, err)
return
}
writeJSON(w, http.StatusOK, struct {
Templates []apps.Template `json:"templates"`
}{Templates: templates})
})

mux.HandleFunc("POST /v1/apps", func(w http.ResponseWriter, r *http.Request) {
var body struct {
Name string `json:"name"`
ParentDir string `json:"parent_dir"`
Type string `json:"type"`
DB bool `json:"db"`
DBService string `json:"db_service"`
PHP string `json:"php"`
Secured bool `json:"secured"`
}
if err := decodeBody(r, &body); err != nil {
writeError(w, statusFor(err), err)
return
}

_, err := apps.Create(r.Context(), apps.CreateRequest{
Root: b.Root(), Name: body.Name, ParentDir: body.ParentDir, Type: body.Type,
DB: body.DB, DBService: body.DBService, PHP: body.PHP, Secured: body.Secured,
Services: func(context.Context) ([]apps.Database, error) {
return AppsDatabases(b.Services()), nil
},
SaveSite: func(site config.Site) error {
return b.Mutate(func(live *config.Config) error {
if existing, ok := live.FindSite(site.Name); ok && (!existing.Parked || filepath.Clean(existing.Path) != filepath.Clean(site.Path)) {
return invalid("a site named %q already exists; choose another project name", site.Name)
}
if err := live.Upsert(site); err != nil {
return invalid("%v", err)
}
return nil
})
},
})
if err != nil {
switch {
case errors.Is(err, apps.ErrInvalid):
writeError(w, http.StatusBadRequest, err)
case errors.Is(err, apps.ErrDownload):
writeError(w, http.StatusBadGateway, err)
default:
writeError(w, statusFor(err), err)
}
return
}

writeJSON(w, http.StatusOK, b.Status())
})
}
148 changes: 148 additions & 0 deletions internal/api/appsapi_test.go
Original file line number Diff line number Diff line change
@@ -0,0 +1,148 @@
package api

import (
"bytes"
"encoding/json"
"net/http"
"net/http/httptest"
"os"
"path/filepath"
"strings"
"testing"

"flock/internal/apps"
"flock/internal/config"
)

func TestAppsTemplatesEndpoint(t *testing.T) {
root := t.TempDir()
if err := os.WriteFile(filepath.Join(root, "apps.conf"), []byte("custom=index.php | db\n"), 0o644); err != nil {
t.Fatal(err)
}
handler := NewHandler(&fakeBackend{root: root}, "")
req := httptest.NewRequest(http.MethodGet, "/v1/apps/templates", nil)
rec := httptest.NewRecorder()
handler.ServeHTTP(rec, req)

if rec.Code != http.StatusOK {
t.Fatalf("GET /v1/apps/templates = %d: %s", rec.Code, rec.Body.String())
}
var out struct {
Templates []apps.Template `json:"templates"`
}
if err := json.Unmarshal(rec.Body.Bytes(), &out); err != nil {
t.Fatal(err)
}
if len(out.Templates) != 4 || out.Templates[1].Name != "custom" || !out.Templates[1].RequiresDB {
t.Fatalf("unexpected templates: %+v", out.Templates)
}
}

func TestCreateAppEndpoint(t *testing.T) {
t.Run("creates-php-app", func(t *testing.T) {
root, parent := t.TempDir(), t.TempDir()
handler := NewHandler(&fakeBackend{root: root}, "")
body, _ := json.Marshal(map[string]any{
"name": "My App",
"parent_dir": parent,
"type": "php",
"php": "8.4",
"secured": true,
})
req := httptest.NewRequest(http.MethodPost, "/v1/apps", bytes.NewReader(body))
rec := httptest.NewRecorder()
handler.ServeHTTP(rec, req)

if rec.Code != http.StatusOK {
t.Fatalf("POST /v1/apps = %d: %s", rec.Code, rec.Body.String())
}
target := filepath.Join(parent, "My App")
if _, err := os.Stat(filepath.Join(target, "index.php")); err != nil {
t.Fatalf("expected index.php: %v", err)
}
cfg, err := config.Load(root)
if err != nil {
t.Fatal(err)
}
site, ok := cfg.FindSite("my-app")
if !ok || site.Path != target || site.PHP != "8.4" || !site.Secured {
t.Fatalf("unexpected saved site: %+v", site)
}
})

t.Run("rejects-missing-db-for-wordpress", func(t *testing.T) {
root, parent := t.TempDir(), t.TempDir()
handler := NewHandler(&fakeBackend{root: root}, "")
body, _ := json.Marshal(map[string]any{
"name": "my-blog",
"parent_dir": parent,
"type": "wordpress",
})
req := httptest.NewRequest(http.MethodPost, "/v1/apps", bytes.NewReader(body))
rec := httptest.NewRecorder()
handler.ServeHTTP(rec, req)

if rec.Code != http.StatusBadRequest || !strings.Contains(rec.Body.String(), "no running database service found") {
t.Fatalf("expected 400 missing DB error, got %d: %s", rec.Code, rec.Body.String())
}
if _, err := os.Stat(filepath.Join(parent, "my-blog")); !os.IsNotExist(err) {
t.Fatalf("expected destination not to be created: %v", err)
}
})

t.Run("rejects-existing-site-before-creating-dir", func(t *testing.T) {
root, parent := t.TempDir(), t.TempDir()
cfg := config.Default()
cfg.Sites = []config.Site{{Name: "demo", Path: parent}}
if err := cfg.Save(root); err != nil {
t.Fatal(err)
}
handler := NewHandler(&fakeBackend{root: root}, "")
body, _ := json.Marshal(map[string]any{
"name": "demo",
"parent_dir": parent,
})
req := httptest.NewRequest(http.MethodPost, "/v1/apps", bytes.NewReader(body))
rec := httptest.NewRecorder()
handler.ServeHTTP(rec, req)

if rec.Code != http.StatusBadRequest {
t.Fatalf("expected 400 conflict, got %d: %s", rec.Code, rec.Body.String())
}
if _, err := os.Stat(filepath.Join(parent, "demo")); !os.IsNotExist(err) {
t.Fatalf("expected destination not to be created: %v", err)
}
})

t.Run("creates-app-inside-parked-parent", func(t *testing.T) {
root, parent := t.TempDir(), t.TempDir()
cfg := config.Default()
cfg.Parked = []string{parent}
if err := cfg.Save(root); err != nil {
t.Fatal(err)
}
handler := NewHandler(&fakeBackend{root: root}, "")
body, _ := json.Marshal(map[string]any{
"name": "parked-app",
"parent_dir": parent,
"type": "php",
"php": "8.4",
"secured": true,
})
req := httptest.NewRequest(http.MethodPost, "/v1/apps", bytes.NewReader(body))
rec := httptest.NewRecorder()
handler.ServeHTTP(rec, req)

if rec.Code != http.StatusOK {
t.Fatalf("POST /v1/apps = %d: %s", rec.Code, rec.Body.String())
}
updated, err := config.Load(root)
if err != nil {
t.Fatal(err)
}
site, ok := updated.FindSite("parked-app")
if !ok || site.Parked || site.Path != filepath.Join(parent, "parked-app") || site.PHP != "8.4" || !site.Secured {
t.Fatalf("unexpected saved site: %+v", site)
}
})
}
11 changes: 11 additions & 0 deletions internal/apps/apps.conf
Original file line number Diff line number Diff line change
@@ -0,0 +1,11 @@
# Templates for `flock app create <name> --type <template>`.
# Each key becomes an available --type value:
# (empty) create an empty directory
# index.php create a starter index.php
# http(s):// download and extract a .tar.gz, .tgz, or .zip archive
# <path> extract a local .tar.gz, .tgz, or .zip archive
# Append `| db` to require a running MySQL or MariaDB service.

blank=
php=index.php
wordpress=https://wordpress.org/latest.tar.gz | db
Loading
Loading