astro-tractstack 2.0.0-rc.3 → 2.0.0-rc.31

package/README.md

@@ -1,53 +1,51 @@
-# Tract Stack
+# TractStack v2
 
-websites that adapt to the visitor
+**Redeeming the web from boring experiences**
 
-by [At Risk Media](https://atriskmedia.com)
+Free web press by [At Risk Media](https://atriskmedia.com)
 
-## epistemic hypermedia server
+## Epistemic Hypermedia Server
 
-...a new species of web 2.0: an outcome of hybrid speciation.
+TractStack is a new species of web platform that makes it possible for millions of websites to adapt to each visitor instead of showing everyone the same thing. It's an **adaptive website builder** that creates fast, beautiful, SEO-ready, and accessible websites that respond intelligently to user behavior.
 
-The `tractstack-go` package provides a backend server for the `astro-tractstack` integration
+Built on [Astro](https://astro.build/) with [HTMX](https://htmx.org/) and a [Golang](https://go.dev/) backend, TractStack uses SQLite by default with optional [Turso](https://app.turso.tech/) cloud database support.
 
-Tract Stack makes it easy for non-technical people to build and grow adaptive websites that are fast, beautiful, SEO-ready, and accessible.
+## Key Features
 
-Tract Stack is built on [Astro](https://astro.build/) with [HTMX](https://htmx.org/) and a [Golang](https://go.dev/) backend -- uses SQLite by default with optional [Turso](https://app.turso.tech/) cloud database
-
-## Documentation
-
-Please visit [our docs](https://tractstack.org)
-
-For production deployment you'll need to prepare your server.
+- **Adaptive Content**: Websites that dynamically respond to visitor behavior
+- **Multi-tenant Architecture**: Host multiple sites from a single installation
+- **Built-in CMS**: StoryKeep content management system
+- **Real-time Updates**: Server-sent events and HTMX for dynamic interactions
+- **Production Ready**: SSL certificates, nginx integration, systemd services
+- **Zero Config Database**: Works out of the box with SQLite3
 
 ## Quick Install
 
-**One-line installer (recommended for Linux):**
+### One-Line Installer
 
 ```bash
-curl -fsSL https://install.tractstack.org | sh
+curl -fsSL https://get.tractstack.com | bash
 ```
 
-This will automatically install both the Go backend and create a new Astro project with TractStack.
+This automatically installs both the Go backend and creates a new Astro project with TractStack integration.
+
+### Installation Options
+
+- `--quick` - Development setup in user directory (no sudo required)
+- `--prod --domain=yourdomain.com` - Production single-tenant
+- `--multi --domain=yourdomain.com` - Production multi-tenant hosting
+- `--dedicated SITE_ID --domain=yourdomain.com` - Isolated dedicated instance
 
 ## Manual Installation
 
 **Prerequisites:**
 
-- Node.js 18
-- pnpm 9+ (recommended) or npm/yarn
-- Go 1.21+
+- Node.js 20+
+- pnpm (recommended) or npm
+- Go 1.22+
 - Git
 
-### Platform Support
-
-**Linux:** Full native support - follow the steps below exactly as written.
-
-**macOS:** Full native support - follow the steps below exactly as written. The installation works the same as Linux.
-
-### Step 1: Install and run the Go backend
-
-**Linux/macOS:**
+### Step 1: Install Go Backend
 
 ```bash
 mkdir -p ~/t8k/src
@@ -57,14 +55,9 @@ cd tractstack-go
 echo "GO_BACKEND_PATH=$HOME/t8k/t8k-go-server/" > .env
 echo "GIN_MODE=release" >> .env
 go build -o tractstack-go ./cmd/tractstack-go
-./tractstack-go
 ```
 
-The backend runs on port 8080 by default.
-
-### Step 2: Create your Astro frontend
-
-**Linux/macOS:**
+### Step 2: Create Astro Frontend
 
 ```bash
 cd ~/t8k
@@ -73,104 +66,240 @@ cd my-tractstack
 pnpm add astro-tractstack@latest
 echo "PRIVATE_GO_BACKEND_PATH=$HOME/t8k/t8k-go-server/" > .env
 npx create-tractstack
+```
+
+### Step 3: Start Development
+
+```bash
+# Terminal 1: Go backend
+cd ~/t8k/src/tractstack-go
+./tractstack-go
+
+# Terminal 2: Astro frontend
+cd ~/t8k/src/my-tractstack
 pnpm dev
 ```
 
-### Step 3: Activate your Story Keep
+Visit https://127.0.0.1:4321 to access your site and activate your Story Keep (CMS).
 
-Visit https://127.0.0.1:4321 in your browser.
+## Installation Types
 
-TractStack works out of the box with local SQLite3 - no database setup required.
+### Development (Quick Install)
 
-**Optional:** You can choose to use [Turso](https://app.turso.tech/) cloud database:
+- Local setup in `~/t8k/`
+- No sudo required
+- Perfect for development and testing
+- SQLite database included
 
-1. Create a database at [turso.tech](https://app.turso.tech/)
-2. Get your database URL and auth token
-3. Activate your database during site init
+### Production Single-Tenant
 
-## Development Workflow
+- System-wide installation at `/home/t8k/`
+- SSL certificates via Let's Encrypt
+- nginx reverse proxy
+- systemd services for automatic startup
+- PM2 process management
 
-1. **Start the Go backend:**
+### Production Multi-Tenant
 
-   ```bash
-   cd ~/t8k/src/tractstack-go
-   ./tractstack-go
-   ```
+- Same as single-tenant plus:
+- Wildcard domain support (`*.yourdomain.com`)
+- Tenant management at `/sandbox/register`
+- Multiple isolated websites from one installation
 
-2. **Start the Astro dev server:**
+### Dedicated Instance
 
-   ```bash
-   cd ~/t8k/src/my-tractstack
-   pnpm dev
-   ```
+- Completely separate installation per site
+- Own source code, binaries, and data
+- Maximum isolation and customization
+- Perfect for agencies managing multiple clients
 
-3. **Access your site:**
-   - Frontend: http://localhost:4321
-   - StoryKeep (CMS): http://localhost:4321/storykeep
+## Project Structure
 
-## Production Deployment
+```
+~/t8k/                              # Development install
+├── src/
+│   ├── tractstack-go/             # Go backend source
+│   │   └── tractstack-go          # Compiled binary
+│   └── my-tractstack/             # Astro frontend
+│       ├── src/
+│       │   ├── components/        # Custom components
+│       │   ├── pages/            # Astro pages
+│       │   └── custom/           # Your customizations
+│       └── astro.config.mjs
+└── t8k-go-server/                 # Backend data storage
+    ├── config/
+    │   ├── t8k/
+    │   │   └── tenants.json       # Tenant registry
+    │   └── default/               # Default tenant config
+    │       ├── env.json           # Core configuration
+    │       ├── brand.json         # Site branding
+    │       ├── knownResources.json # Resource tracking
+    │       ├── tailwindWhitelist.json # CSS optimization
+    │       └── media/             # Media files
+    │           ├── images/
+    │           └── css/
+    ├── db/
+    │   └── default/
+    │       └── tractstack.db      # SQLite database
+    └── log/
+        ├── system.log
+        ├── tenant.log
+        └── database.log
+```
 
-For production, you'll need:
+### Production Structure
 
-1. **Deploy the Go backend** with proper environment variables
-2. **Build and deploy the Astro frontend** with `pnpm build`
-3. **Configure your database** connection
-4. **Set up SSL/TLS** for your domain
+Production installations live at `/home/t8k/` with the same structure plus:
 
-See our [deployment guide](https://tractstack.org/docs/deployment) for detailed instructions.
+```
+/home/t8k/
+├── bin/
+│   └── tractstack-go             # Production binary
+├── etc/
+│   ├── letsencrypt/             # SSL certificates
+│   ├── pm2/                     # PM2 configs
+│   └── t8k-ports.conf           # Port allocations
+├── scripts/
+│   └── t8k-concierge.sh         # Build automation
+└── state/                       # Build queue
+```
 
 ## Multi-Tenant Features
 
-TractStack supports multi-tenancy!
+TractStack v2 includes powerful multi-tenant capabilities:
 
-## Project Structure
+- **Tenant Registration**: Self-service tenant creation at `/sandbox/register`
+- **Domain Routing**: Automatic subdomain routing (`tenant.yourdomain.com`)
+- **Isolated Data**: Each tenant has separate databases and media
+- **Capacity Management**: Configurable tenant limits
+- **Email Activation**: Automated tenant activation emails
+
+## SSL Certificate Management
+
+### Cloudflare DNS (Automated)
+
+Create `/root/.secrets/certbot/cloudflare.ini`:
 
+```ini
+dns_cloudflare_api_token = YOUR_API_TOKEN_HERE
 ```
-## Project Structure
 
-Installs in ~/t8k and scopes to tenantId=`default` when ENABLE_MULTI_TENANT=false
+Certificates are obtained automatically during installation.
+
+### Manual DNS Verification
+
+Without Cloudflare, the installer guides you through manual DNS TXT record verification.
+
+## Service Management
 
-For multiple Tract Stack sites on a single server see our production install recipes.
+### Main Installation
 
+```bash
+# Status
+sudo systemctl status tractstack-go
+sudo -u t8k pm2 status astro-main
+
+# Restart
+sudo systemctl restart tractstack-go
+sudo -u t8k pm2 restart astro-main
+
+# Logs
+sudo journalctl -u tractstack-go -f
+sudo -u t8k pm2 logs astro-main
 ```
 
-~/t8k/
-├── src/
-│ ├── tractstack-go/ # Go backend source
-│ │ ├── tractstack-go # Compiled binary
-│ │ └── ...
-│ └── my-tractstack/ # Astro frontend
-│ ├── src/
-│ │ ├── custom/ # Your custom components
-│ │ ├── pages/
-│ │ └── ...
-└── t8k-go-server/ # Backend data storage
-├── config/
-│ ├── t8k/
-│ │ └── tenants.json # Source of truth
-│ └── default/ # Default tenant config
-│ └── env.json # Critical config
-│ └── brand.json # Personalization
-│ └── media/ # Tenant media files
-├── db/
-│ └── default/
-│ └── tractstack.db # SQLite database
-└── log/
-├── system.log
-├── tenant.log
-├── database.log
-└── ...
+### Dedicated Instances
+
+```bash
+# Replace SITE_ID with your site identifier
+sudo systemctl status tractstack-go@SITE_ID
+sudo -u t8k pm2 status astro-SITE_ID
+```
+
+## Build System
 
+The build concierge processes automated builds via CSV files in `/home/t8k/state/`:
+
+```csv
+type=main,tenant=default,command=build
+type=dedicated,site=SITE_ID,command=build
 ```
 
+The system automatically:
+
+1. Pulls latest code from Git
+2. Builds Go backend and Astro frontend
+3. Extracts Tailwind CSS optimizations
+4. Restarts services
+5. Cleans up processed files
+
+## Database Options
+
+### SQLite (Default)
+
+- Zero configuration required
+- Perfect for most websites
+- Automatic backups and maintenance
+- Scales to hundreds of thousands of visitors
+
+### Turso Cloud Database
+
+- Distributed SQLite with global replication
+- Configure during site initialization
+- Seamless scaling for high-traffic sites
+- Built-in analytics and monitoring
+
+## Development Workflow
+
+1. **Edit Content**: Use StoryKeep CMS at `/storykeep`
+2. **Customize Design**: Modify components in `src/custom/`
+3. **Add Features**: Create CodeHooks for dynamic functionality
+4. **Test Changes**: Hot reloading with `pnpm dev`
+5. **Deploy**: Automated builds handle production updates
+
+## API Integration
+
+TractStack provides RESTful APIs for:
+
+- Content management
+- User analytics
+- Belief tracking (visitor preferences)
+- Multi-tenant operations
+- Media handling
+
+## Uninstalling
+
+**For Production installations**, the uninstall script is located at `/home/t8k/scripts/`:
+
+```bash
+sudo /home/t8k/scripts/t8k-uninstall.sh
 ```
 
-The Go backend stores data in `~/t8k/t8k-go-server/` by default (quick install).
+**For Quick install (development)**, the script is in:
+
+```bash
+sudo ~/t8k/src/tractstack-go/pkg/scripts/t8k-uninstall.sh
+```
 
-## Queries?
+## Support & Documentation
 
-Reach out at hello -at- tractstack -dot- com
+- **Documentation**: https://tractstack.org
+- **GitHub Issues**: https://github.com/AtRiskMedia/tractstack-go/issues
+- **Email Support**: hello@tractstack.com
+- **Community**: Join discussions about adaptive web experiences
 
 ## License
 
-Functional Source License, Version 1.1, MIT Future License
+**Functional Source License (FSL)** - Commercial use encouraged!
+
+The only restriction is no re-selling TractStack as-a-service. Perfect for:
+
+- Agency client projects
+- Corporate websites
+- Personal projects
+- Open source contributions
+
+---
+
+_TractStack v2 - Making the web adaptive, one site at a time_  
+_Made with ❤️ by [At Risk Media](https://atriskmedia.com)_

package/bin/create-tractstack.js

@@ -29,16 +29,25 @@ function detectPackageManager() {
 }
 
 // Parse existing .env file
-function parseExistingEnv() {
+function getEnvState() {
   const defaults = {
     goBackend: 'http://localhost:8080',
     tenantId: 'default',
     goBackendPath: `${homedir()}/t8k-go-server/`,
     enableMultiTenant: false,
+    enableBunny: false,
+  };
+
+  const found = {
+    goBackend: false,
+    tenantId: false,
+    goBackendPath: false,
+    enableMultiTenant: false,
+    enableBunny: false,
   };
 
   if (!existsSync('.env')) {
-    return defaults;
+    return { envDefaults: defaults, envState: found };
   }
 
   try {
@@ -50,7 +59,6 @@ function parseExistingEnv() {
       if (line && !line.startsWith('#')) {
         const [key, ...valueParts] = line.split('=');
         if (key && valueParts.length > 0) {
-          // Remove surrounding quotes and trim
           let value = valueParts.join('=').trim();
           if (
             (value.startsWith('"') && value.endsWith('"')) ||
@@ -64,17 +72,30 @@ function parseExistingEnv() {
     });
 
     return {
-      goBackend: envVars.PUBLIC_GO_BACKEND || defaults.goBackend,
-      tenantId: envVars.PUBLIC_TENANTID || defaults.tenantId,
-      goBackendPath: envVars.PRIVATE_GO_BACKEND_PATH || defaults.goBackendPath,
-      enableMultiTenant:
-        envVars.ENABLE_MULTI_TENANT === 'true' || defaults.enableMultiTenant,
+      envDefaults: {
+        goBackend: envVars.PUBLIC_GO_BACKEND || defaults.goBackend,
+        tenantId: envVars.PUBLIC_TENANTID || defaults.tenantId,
+        goBackendPath:
+          envVars.PRIVATE_GO_BACKEND_PATH || defaults.goBackendPath,
+        enableMultiTenant:
+          envVars.PUBLIC_ENABLE_MULTI_TENANT === 'true' ||
+          defaults.enableMultiTenant,
+        enableBunny:
+          envVars.PUBLIC_ENABLE_BUNNY === 'true' || defaults.enableBunny,
+      },
+      envState: {
+        goBackend: !!envVars.PUBLIC_GO_BACKEND,
+        tenantId: !!envVars.PUBLIC_TENANTID,
+        goBackendPath: !!envVars.PRIVATE_GO_BACKEND_PATH,
+        enableMultiTenant: envVars.PUBLIC_ENABLE_MULTI_TENANT !== undefined,
+        enableBunny: envVars.PUBLIC_ENABLE_BUNNY !== undefined,
+      },
     };
   } catch (error) {
     console.log(
       kleur.yellow('⚠️ Found .env file but could not parse it, using defaults')
     );
-    return defaults;
+    return { envDefaults: defaults, envState: found };
   }
 }
 
@@ -140,7 +161,7 @@ ${kleur.bold('Examples:')}
   }
 
   // Parse existing .env values
-  const envDefaults = parseExistingEnv();
+  const { envDefaults, envState } = getEnvState();
   const hasExistingEnv = existsSync('.env');
 
   if (hasExistingEnv) {
@@ -151,9 +172,11 @@ ${kleur.bold('Examples:')}
     );
   }
 
-  // Prompt for configuration with existing values as defaults
-  const responses = await prompts([
-    {
+  // Build prompts array conditionally - only prompt for values not in .env
+  const promptQuestions = [];
+
+  if (!envState.goBackend) {
+    promptQuestions.push({
       type: 'text',
       name: 'goBackend',
       message: 'TractStack Go backend URL:',
@@ -166,21 +189,61 @@ ${kleur.bold('Examples:')}
           return 'Please enter a valid URL';
         }
       },
-    },
-    {
+    });
+  } else {
+    console.log(
+      kleur.green(`✓ Using Go backend URL: ${envDefaults.goBackend}`)
+    );
+  }
+
+  if (!envState.enableMultiTenant && !enableMultiTenant) {
+    promptQuestions.push({
       type: 'confirm',
       name: 'enableMultiTenant',
       message: 'Enable multi-tenant functionality?',
       initial: enableMultiTenant || envDefaults.enableMultiTenant,
-    },
-    {
-      type: (prev, values) => (values.enableMultiTenant ? 'text' : null),
+    });
+  } else {
+    const willEnable = enableMultiTenant || envDefaults.enableMultiTenant;
+    console.log(
+      kleur.green(
+        `✓ Multi-tenant functionality: ${willEnable ? 'enabled' : 'disabled'}`
+      )
+    );
+  }
+
+  if (!envState.enableBunny) {
+    promptQuestions.push({
+      type: 'confirm',
+      name: 'enableBunny',
+      message: 'Enable Bunny Video Player?',
+      initial: envDefaults.enableBunny,
+    });
+  } else {
+    console.log(
+      kleur.green(
+        `✓ Bunny Video Player: ${envDefaults.enableBunny ? 'enabled' : 'disabled'}`
+      )
+    );
+  }
+
+  // Only prompt for tenantId if multi-tenant will be enabled and tenantId not in .env
+  const willEnableMultiTenant =
+    enableMultiTenant || envDefaults.enableMultiTenant;
+  if (willEnableMultiTenant && !envState.tenantId) {
+    promptQuestions.push({
+      type: 'text',
       name: 'tenantId',
       message: 'Tenant ID:',
       initial: envDefaults.tenantId,
       validate: (value) => value.length > 0 || 'Tenant ID is required',
-    },
-    {
+    });
+  } else if (willEnableMultiTenant) {
+    console.log(kleur.green(`✓ Using Tenant ID: ${envDefaults.tenantId}`));
+  }
+
+  if (!envState.goBackendPath) {
+    promptQuestions.push({
       type: 'text',
       name: 'goBackendPath',
       message: 'TractStack Go backend path:',
@@ -191,37 +254,61 @@ ${kleur.bold('Examples:')}
         }
         return true;
       },
-    },
-    {
-      type: 'confirm',
-      name: 'includeExamples',
-      message:
-        'Include CodeHook examples? (custom components, collections route)',
-      initial: includeExamples,
-    },
-  ]);
+    });
+  } else {
+    console.log(
+      kleur.green(`✓ Using Go backend path: ${envDefaults.goBackendPath}`)
+    );
+  }
+
+  // Always ask about examples (not stored in .env)
+  promptQuestions.push({
+    type: 'confirm',
+    name: 'includeExamples',
+    message:
+      'Include CodeHook examples? (custom components, collections route)',
+    initial: includeExamples,
+  });
 
-  if (!responses.goBackend) {
-    console.log(kleur.red('\n❌ Setup cancelled.'));
+  // Run prompts only if there are questions
+  const responses =
+    promptQuestions.length > 0 ? await prompts(promptQuestions) : {};
+
+  // Merge responses with env defaults for final values
+  const finalResponses = {
+    goBackend: responses.goBackend || envDefaults.goBackend,
+    enableMultiTenant:
+      responses.enableMultiTenant === true || // explicit true from prompt
+      enableMultiTenant || // CLI flag --multi-tenant
+      envDefaults.enableMultiTenant === true, // existing .env value was "true"
+    enableBunny: responses.enableBunny ?? envDefaults.enableBunny,
+    tenantId: responses.tenantId || envDefaults.tenantId,
+    goBackendPath: responses.goBackendPath || envDefaults.goBackendPath,
+    includeExamples: responses.includeExamples ?? includeExamples,
+  };
+
+  if (!finalResponses.goBackend) {
+    console.log(kleur.red('\n✗ Setup cancelled.'));
     process.exit(1);
   }
 
   // Use existing tenantId if multi-tenant is disabled
-  const finalTenantId = responses.enableMultiTenant
-    ? responses.tenantId
+  const finalTenantId = finalResponses.enableMultiTenant
+    ? finalResponses.tenantId
     : envDefaults.tenantId;
 
   if (!finalTenantId) {
-    console.log(kleur.red('\n❌ Setup cancelled - Tenant ID is required.'));
+    console.log(kleur.red('\n✗ Setup cancelled - Tenant ID is required.'));
     process.exit(1);
   }
 
   // Create .env file
   const envContent = `# TractStack Configuration
-PUBLIC_GO_BACKEND="${responses.goBackend}"
+PUBLIC_GO_BACKEND="${finalResponses.goBackend}"
 PUBLIC_TENANTID="${finalTenantId}"
-PRIVATE_GO_BACKEND_PATH="${responses.goBackendPath.endsWith('/') ? responses.goBackendPath : responses.goBackendPath + '/'}"
-${responses.enableMultiTenant ? 'ENABLE_MULTI_TENANT="true"' : ''}
+PRIVATE_GO_BACKEND_PATH="${finalResponses.goBackendPath.endsWith('/') ? finalResponses.goBackendPath : finalResponses.goBackendPath + '/'}"
+PUBLIC_ENABLE_MULTI_TENANT="${finalResponses.enableMultiTenant ? 'true' : 'false'}"
+PUBLIC_ENABLE_BUNNY="${finalResponses.enableBunny ? 'true' : 'false'}"
 `;
 
   try {
@@ -529,17 +616,10 @@ export default defineConfig({
   const runCommand =
     packageManager === 'pnpm' ? 'pnpm run' : `${packageManager} run`;
 
-  console.log('\nNext steps:');
-  console.log(kleur.cyan('1. Start your Go backend:'));
-  console.log('   tractstack-go');
-  console.log(kleur.cyan('2. Start your Astro development server:'));
-  console.log(`   ${runCommand} dev`);
-
   if (responses.enableMultiTenant) {
     console.log('\n' + kleur.bold('Multi-tenant features enabled:'));
     console.log(`  • Tenant registration: ${kleur.cyan('/sandbox/register')}`);
     console.log(`  • Subdomain routing middleware added`);
-    console.log(`  • Admin-only tenant management`);
     console.log(
       `\n${kleur.yellow('Note:')} Make sure your Go backend has ENABLE_MULTI_TENANT=true`
     );
@@ -553,7 +633,7 @@ export default defineConfig({
     console.log(`  • Custom components and CodeHooks`);
   }
 
-  console.log('\n📚 Documentation: https://tractstack.org/docs');
+  console.log('\n📚 Documentation: https://tractstack.org');
 }
 
 main().catch(console.error);