mirror of
https://github.com/pockethost/pockethost.git
synced 2025-03-30 15:08:30 +00:00
enh: add caddy for local dev & update documentation
This commit is contained in:
Ben Allfree
parent
0c2e70c83f
commit
185a121545
@ -32,8 +32,8 @@ DAEMON_PB_HOOKS_DIR=$ROOT/packages/daemon/pb_hooks
|
||||
|
||||
# The username and password of the admin account PocketHost will use to perform
|
||||
# privileged backend operations
|
||||
DAEMON_PB_USERNAME=admin@pockethost.test
|
||||
DAEMON_PB_PASSWORD=admin@pockethost.test
|
||||
DAEMON_PB_USERNAME=admin@pockethost.lvh.me
|
||||
DAEMON_PB_PASSWORD=admin@pockethost.lvh.me
|
||||
|
||||
# The port the daemon listens on
|
||||
DAEMON_PORT=80
|
||||
|
||||
43
Caddyfile
Normal file
43
Caddyfile
Normal file
@ -0,0 +1,43 @@
|
||||
# ================
|
||||
# Marketing/blog
|
||||
# ================
|
||||
pockethost.lvh.me {
|
||||
reverse_proxy localhost:8080
|
||||
tls internal
|
||||
}
|
||||
|
||||
|
||||
# ================
|
||||
# Dashboard
|
||||
# ================
|
||||
app.pockethost.lvh.me {
|
||||
reverse_proxy localhost:5173
|
||||
tls internal
|
||||
}
|
||||
|
||||
|
||||
|
||||
|
||||
# ================
|
||||
# Mothership
|
||||
# ================
|
||||
pockethost-central.pockethost.lvh.me {
|
||||
reverse_proxy localhost:8090
|
||||
tls internal
|
||||
log {
|
||||
output stdout
|
||||
level DEBUG
|
||||
}
|
||||
}
|
||||
|
||||
# ================
|
||||
# Edgeworker
|
||||
# ================
|
||||
*.pockethost.lvh.me {
|
||||
reverse_proxy localhost:3000
|
||||
tls internal
|
||||
log {
|
||||
output stdout
|
||||
level DEBUG
|
||||
}
|
||||
}
|
||||
@ -1,13 +1,3 @@
|
||||
---
|
||||
title: Just the frontend (Svelte)
|
||||
category: development
|
||||
description: Learn how to focus purely on UI and frontend development using
|
||||
Svelte with pockethost.io. Simply clone our repository, install the needed
|
||||
packages and start a local build to connect directly to the `pockethost.io`
|
||||
mothership for seamless database tasks. No backend setup, all fun and
|
||||
function.
|
||||
---
|
||||
|
||||
Just want to work with the UI and frontend?
|
||||
|
||||
```bash
|
||||
|
||||
24
docs/full-stack.md
Normal file
24
docs/full-stack.md
Normal file
@ -0,0 +1,24 @@
|
||||
**Running in dev mode**
|
||||
|
||||
Note for OS X users: if `pocketbase` does not run, it's probably your [security settings](https://support.apple.com/guide/mac-help/open-a-mac-app-from-an-unidentified-developer-mh40616/mac).
|
||||
|
||||
**Prerequisites**
|
||||
|
||||
```bash
|
||||
brew install caddy
|
||||
```
|
||||
|
||||
Then:
|
||||
|
||||
```bash
|
||||
git clone git@github.com:benallfree/pockethost.git
|
||||
cd pockethost
|
||||
yarn
|
||||
cp .env-template .env # modify as needed, if you used `pockethost.test` for your local domain, everything should work
|
||||
|
||||
yarn dev
|
||||
open https://pockethost.test
|
||||
open https://pockethost-central.pockethost.test
|
||||
# login: admin@pockethost.test (change in .env)
|
||||
# password: admin@pockethost.test (change in .env)
|
||||
```
|
||||
@ -1,92 +0,0 @@
|
||||
---
|
||||
title: Never touch your local /etc/hosts file in OS X again
|
||||
category: development
|
||||
subcategory: full-stack
|
||||
description: Learn how to streamline your developer experience by setting up
|
||||
your computer to automatically handle *.test domains using Homebrew and
|
||||
Dnsmasq. Say goodbye to manually editing your hosts file each time. This guide
|
||||
offers an easy-to-follow process for both setup and testing, ensuring smoother
|
||||
project management and development.
|
||||
|
||||
---
|
||||
|
||||
# Overview
|
||||
|
||||
Ever had to edit your /etc/hosts file on your OS X machine each time you spin up a new *.test domain? If so, you know it can be a manual, time-consuming process. But, good news! I'm about to teach you how to automate this using Homebrew and Dnsmasq. With the right setup, your computer will handle these domains effortlessly, streamlining your developer experience.
|
||||
|
||||
To get started, you'll need Homebrew installed. Next up, you'll install Dnsmasq using a simple brew command. You'll then create a specific config directory, followed by setting up your *.test domains, and configuring the port to the default DNS port. It may sound a bit technical, but don't worry, I've got you covered with a step-by-step guide.
|
||||
|
||||
Once the setup is complete, we will move on to autostarting it now and setting it to autostart after each reboot. Then, onto the fun part, testing! We'll test the new setup, create a resolver directory and add your nameserver to the resolvers. The aim is to ensure smooth project management and development, and most importantly, never having to manually edit your hosts file each time you create a new *.test domain. Rejoice in the simplified brilliance of your new development process!
|
||||
|
||||
|
||||
> To set up your computer to work with \*.test domains, e.g. project.test, awesome.test and so on, without having to add to your hosts file each time.
|
||||
|
||||
## Requirements
|
||||
|
||||
- [Homebrew](https://brew.sh/)
|
||||
|
||||
## Install
|
||||
|
||||
```
|
||||
brew install dnsmasq
|
||||
```
|
||||
|
||||
## Setup
|
||||
|
||||
### Create config directory
|
||||
|
||||
```
|
||||
mkdir -pv $(brew --prefix)/etc/
|
||||
```
|
||||
|
||||
### Setup \*.test
|
||||
|
||||
```
|
||||
echo 'address=/.test/127.0.0.1' >> $(brew --prefix)/etc/dnsmasq.conf
|
||||
```
|
||||
|
||||
### Change port to default DNS port
|
||||
|
||||
```
|
||||
echo 'port=53' >> $(brew --prefix)/etc/dnsmasq.conf
|
||||
```
|
||||
|
||||
## Autostart - now and after reboot
|
||||
|
||||
```
|
||||
sudo brew services start dnsmasq
|
||||
```
|
||||
|
||||
## Test
|
||||
|
||||
```
|
||||
dig testing.testing.one.two.three.test @127.0.0.1
|
||||
```
|
||||
|
||||
## Add to resolvers
|
||||
|
||||
### Create resolver directory
|
||||
|
||||
```
|
||||
sudo mkdir -v /etc/resolver
|
||||
```
|
||||
|
||||
### Add your nameserver to resolvers
|
||||
|
||||
```
|
||||
sudo bash -c 'echo "nameserver 127.0.0.1" > /etc/resolver/test'
|
||||
```
|
||||
|
||||
### Test
|
||||
|
||||
```
|
||||
---
|
||||
title: Make sure you haven't broken your DNS.
|
||||
---
|
||||
ping -c 1 www.google.com
|
||||
---
|
||||
title: Check that .dev names work
|
||||
---
|
||||
ping -c 1 this.is.a.test.test
|
||||
ping -c 1 iam.the.walrus.test
|
||||
```
|
||||
@ -1,40 +0,0 @@
|
||||
---
|
||||
title: Manually set up `/etc/hosts`
|
||||
category: development
|
||||
subcategory: full-stack
|
||||
description: Learn how to manually configure your host entries with PocketHost
|
||||
for developers who can't utilize dnsmasq or similar tools. Navigate a slightly
|
||||
streamlined dev experience while you expand your project's reach using
|
||||
PocketHost, with support for as many '*.pockethost.test' subdomains as
|
||||
required.
|
||||
|
||||
---
|
||||
|
||||
# Overview
|
||||
|
||||
It's possible to manually fine-tune your host entries with PocketHost, particularly when dnsmasq and related tools are out of the question. This method offers a slightly stripped-down but nonetheless effective developer experience. Further, it supports an unlimited number of '*.pockethost.test' subdomains, enabling you to touch a wider audience as you grow your project with PocketHost.
|
||||
|
||||
Seize control by adding host entries to the `/etc/hosts` file. Begin by bringing up the file with a text editor like nano. Lines specified under the file associate IP addresses with host names.
|
||||
|
||||
Here, `127.0.0.1` directs to your local machine. Following it, you'll add 'pockethost.test'—the main domain—along with other subdomains like 'pockethost-central.pockethost.test'—the primary PocketBase instance—and 'test.pockethost.test'—an illustrative PocketBase instance at the user level.
|
||||
|
||||
The manual method requires specifying subdomains individually as `/etc/hosts` doesn't interpret wildcards. Therefore, you're required to add as many '*.pockethost.test' subdomains as necessary for testing manually. Although slightly more time-consuming, taking this approach ensures a steadfast connection between your development environment and PocketBase through PocketHost.
|
||||
|
||||
|
||||
If you can't use [dnsmasq](/docs/development/full-stack/dnsmasq/) or equivalent, you can still configure hosts manually. The dev experience will be slightly more limited, but it will still work.
|
||||
|
||||
**1. Add host entries to `/etc./hosts`**
|
||||
|
||||
```bash
|
||||
sudo nano /etc/hosts
|
||||
```
|
||||
|
||||
Then, add these entries:
|
||||
|
||||
```
|
||||
127.0.0.1 pockethost.test # The main domain
|
||||
127.0.0.1 pockethost-central.pockethost.test # The main pocketbase instance
|
||||
127.0.0.1 test.pockethost.test # A sample (user) pocketbase instance
|
||||
```
|
||||
|
||||
Add as many `*.pockethost.test` subdomains as you want to test. Since `/etc/hosts` does not support wild-carding, this must be done manually.
|
||||
@ -1,41 +0,0 @@
|
||||
---
|
||||
title: All our base
|
||||
category: development
|
||||
subcategory: full-stack
|
||||
description: Explore how to run the entire pockethost.io stack locally, from
|
||||
setting up local SSL wildcard domain to launching the platform. This guide
|
||||
covers the necessary preparations and gives a step-by-step walkthrough to run
|
||||
in dev mode, making backend setup a breeze, even in a local environment.
|
||||
---
|
||||
|
||||
# Overview
|
||||
|
||||
It's time for some thrilling backstage moments with pockethost.io! We've always loved the idea of you diving deep into our inner mechanics here at PocketHost. Why should cloud hosting have all the fun, right? So let's hit the ground running and explore how you can operate the entire pockethost.io stack right from your local environment, from configuring a local SSL wildcard domain to getting the platform up and running.
|
||||
|
||||
Let's be clear, this isn't beginner stuff. You can run the entire stack locally and that's no small feat. This means you can spin up a complete PocketHost platform on your personal machine, making your local back-end environment mirror that of production. This comes in handy for debugging, new feature development or just to gain a solid understanding of how the gears of PocketHost mesh together.
|
||||
|
||||
Moving on, you should note that you need a local SSL wildcard domain set up to get started. For our OS X users, if you encounter difficulty running `pocketbase`, your machine's security settings could likely be the impediment. Fear not, a helpful link has been included for troubleshooting this common hiccup. Now that we've got that covered, my friends, it's time for some hands-on action with pockethost.io in your own habitat!
|
||||
|
||||
Stay patient, stay curious, and above all, remember: Movement defines everything we do, whether it's a line of code or a jiu jitsu match! Let's put that core philosophy into practice.
|
||||
|
||||
The entire pockethost.io stack can be run locally.
|
||||
|
||||
**Prerequisites**
|
||||
|
||||
- Local SSL wildcard domain - [local domain setup instructions](/docs/development/full-stack/local-domain-setup/)
|
||||
|
||||
**Running in dev mode**
|
||||
|
||||
Note for OS X users: if `pocketbase` does not run, it's probably your [security settings](https://support.apple.com/guide/mac-help/open-a-mac-app-from-an-unidentified-developer-mh40616/mac).
|
||||
|
||||
```bash
|
||||
git clone git@github.com:benallfree/pockethost.git
|
||||
cd pockethost
|
||||
yarn
|
||||
cp .env-template .env # modify as needed, if you used `pockethost.test` for your local domain, everything should work
|
||||
scripts/dev.sh
|
||||
open https://pockethost.test
|
||||
open https://pockethost-central.pockethost.test
|
||||
# login: admin@pockethost.test (change in .env)
|
||||
# password: admin@pockethost.test (change in .env)
|
||||
```
|
||||
@ -1,59 +0,0 @@
|
||||
---
|
||||
title: Local Domain Setup Instructions
|
||||
category: development
|
||||
subcategory: full-stack
|
||||
description: Configure your local development environment to use wildcard
|
||||
domains with SSL for the full Dockerized stack for PocketHost. This guide
|
||||
covers steps from generating a root certificate for self-signing, approving
|
||||
the self-signed certificate in your browser, generating a wildcard domain
|
||||
certificate, to configuring your machine for wildcard localhost domains.
|
||||
|
||||
---
|
||||
|
||||
# Overview
|
||||
|
||||
In developing the full Dockerized stack for PocketHost, we're faced with the challenge of configuring our local dev environment to recognize wildcard domains operating via SSL. This may seem intimidating at first, but we've got it all covered in a few planed out steps.
|
||||
|
||||
Start by generating a root certificate for self-signing with the `create-ca.sh` script found in the `ssl` directory. The self-signed certificate needs your approval in your web browser to function correctly. If you follow the workflow using FireFox OS X, it's a straightforward process: navigate to your settings page, search for 'cert', opt for 'View Certificates', and finally import `ca.crt` under the `Authorities` tab. For other browsers or operating systems, consult the instructions laid out on BenMorel's dev-certificates GitHub repository.
|
||||
|
||||
Next, it's vital to devise a wildcard domain certificate for `pocketbase.test`. Then gear up your machine to be familiar with wildcard localhost domains. Operating on OS X? Refer to the listed dnsmasq instructions. Don't forget to restart dnsmasq services each time. If you're not up for using dnsmasq, manual `/etc/hosts` setup instructions are right there for your convenience.
|
||||
|
||||
|
||||
This document covers how to set up your local development environment to recognize wildcard domains with SSL. Developing the full Dockerized stack for PocketHost requires these steps.
|
||||
|
||||
**1. Generate a root certificate for self-signing.**
|
||||
|
||||
```bash
|
||||
cd ssl
|
||||
./create-ca.sh
|
||||
```
|
||||
|
||||
**2. Manually approve the self-signed certificate in your browser.**
|
||||
|
||||
For FireFox OS X, do this:
|
||||
|
||||
1. Open settings page.
|
||||
2. Search for "cert"
|
||||
3. Click `View Certificates`
|
||||
4. Move to the `Authorities` tab
|
||||
5. Import `ca.crt`
|
||||
|
||||
For other browsers and operating systems, follow the instructions here: https://github.com/BenMorel/dev-certificates
|
||||
|
||||
**3. Generate a wildcard domain cert for `pockethost.test`**
|
||||
|
||||
```
|
||||
./create-certificate pockethost.test
|
||||
```
|
||||
|
||||
**4. Configure your machine to recognize wildcard localhost domains.**
|
||||
|
||||
If you are on OS X, follow the [dnsmasq instructions](/docs/development/full-stack/dnsmasq/) to set up your local machine for the ultimate local domain wildcard dev experience.
|
||||
|
||||
Remember to start `dnsmasq` every time:
|
||||
|
||||
```bash
|
||||
brew services restart dnsmasq
|
||||
```
|
||||
|
||||
If you don't want to use `dnsmasq`, follow the [manual /etc/hosts setup instructions](/docs/development/full-stack/etc_hosts/).
|
||||
@ -1,14 +1,3 @@
|
||||
---
|
||||
title: Getting Started
|
||||
category: hosting
|
||||
description: Explore how to set up a production-grade hosting environment for
|
||||
PocketHost. Whether you crave control over underlying infrastructure or wish
|
||||
to run it from unoffered regions, this guide provides needful insights into
|
||||
managing Docker, handling DNS, provisioning SSL certs, and understanding cloud
|
||||
computing or VPS deployment. Discover PocketHost's abilities to transform your
|
||||
song.
|
||||
---
|
||||
|
||||
# Overview
|
||||
|
||||
Power up your projects by hosting PocketHost independently. If control is what you crave, or your project operates out of pockethost.io's reach, then this guide is just what you need. Here, we unravel the intimidating knots of Docker management, DNS handling, and SSL certificate provisioning. We also offer a bird's eye view of both Cloud Computing and VPS deployment. In essence, you're about to embark on a DIY journey into the belly of PocketHost, and we're here to guide you.
|
||||
|
||||
@ -1,13 +1,3 @@
|
||||
---
|
||||
title: Introduction
|
||||
category: overview
|
||||
description: PocketHost, a powerful cloud hosting platform for PocketBase,
|
||||
allows you to create unlimited projects quickly and easily. With no backend
|
||||
setup required, it manages all the Linux/devops tasks, from email and DNS
|
||||
jargon to SSL management and CDN hosting, so developers can solely focus on
|
||||
building their apps.
|
||||
---
|
||||
|
||||
# 👋 Welcome to PocketHost
|
||||
|
||||
## Overview
|
||||
|
||||
@ -1,13 +1,3 @@
|
||||
---
|
||||
title: Developing PocketHost
|
||||
category: development
|
||||
description: Learn how to develop PocketHost, a powerful, open-source, nodejs
|
||||
application that enables swift multi-tenant platform functions. Ideal for
|
||||
public or private use, PocketHost is beginner-friendly with plenty of
|
||||
front-end modifications, while offering complex backend setup opportunities
|
||||
for seasoned developers.
|
||||
---
|
||||
|
||||
This monorepo contains the entire open source stack that powers pockethost.io. You can use it to run your own private or public multitenant platform.
|
||||
|
||||
PocketHost is a pure nodejs application. It used to run in a Docker container, but it was eventually decided that a pure node stack was a better option.
|
||||
|
||||
@ -1,12 +1,3 @@
|
||||
---
|
||||
title: Production Deployment
|
||||
category: development
|
||||
description: Learn how to deploy your PocketHost project for production. This
|
||||
guide covers building, refreshing Certbot, running tests, as well as updating
|
||||
and maintaining PocketBase's max semver. Dive in and get your applications
|
||||
running smoothly in no time.
|
||||
---
|
||||
|
||||
## Summary
|
||||
|
||||
- `sudo crontab -e`
|
||||
|
||||
10
docs/rpc.md
10
docs/rpc.md
@ -1,13 +1,3 @@
|
||||
---
|
||||
title: Creating RPC Calls
|
||||
category: development
|
||||
description: Learn how to secure data modifications with PocketHost by creating
|
||||
Remote Procedure Calls (RPC). Our guide comprehensively covers how to produce
|
||||
new RPC calls, adjust the schema, and handle commands. Currently, only
|
||||
asynchronous executions are supported, with returns from RPC calls
|
||||
unavailable. Ideal for nodejs programmers seeking robust security measures.
|
||||
---
|
||||
|
||||
For security, PocketHost does not allow modification of records by the frontend PocketBase client. Instead, the frontend must send an RPC request which the backend will securely process. This allows for many security vulnerabilities to be addressed which PocketBase admin security rules cannot. In particular, PocketBase admin security rules fall short in these scenarios:
|
||||
|
||||
- When the incoming data cannot be validated declaratively
|
||||
|
||||
@ -12,6 +12,9 @@
|
||||
"build:daemon": "cd packages/daemon && yarn build",
|
||||
"build:www": "cd packages/www && yarn build",
|
||||
"dev": "concurrently 'yarn:dev:*'",
|
||||
"dev:caddy": "source .env && caddy run",
|
||||
"dev:www": "cd packages/www && yarn start",
|
||||
"dev:dashboard": "cd packages/dashboard && yarn dev",
|
||||
"dev:daemon": "cd packages/daemon && yarn dev",
|
||||
"start": "concurrently 'yarn:start:*'",
|
||||
"start:daemon": "cd packages/daemon && yarn start",
|
||||
|
||||
@ -7,7 +7,7 @@
|
||||
"build:docker": "cd src/services/PocketBaseService && docker build -t pockethost/pocketbase .",
|
||||
"build:hooks": "tsup --target es5 ./src/hooks/src/*.ts -d ./pb_hooks && prettier -w \"./pb_hooks/*\"",
|
||||
"dev": "concurrently 'yarn:dev:*'",
|
||||
"dev:server": "tsx watch src/server.ts",
|
||||
"dev:server": "source ../../.env && DEBUG=1 tsx watch src/server.ts",
|
||||
"dev:hooks": "chokidar './src/hooks/**' -c 'yarn build:hooks' --initial",
|
||||
"ddos": "NODE_ENV=development tsx watch src/stresser/index.ts",
|
||||
"start": "tsx src/server.ts",
|
||||
|
||||
@ -1,11 +0,0 @@
|
||||
#!/bin/bash
|
||||
|
||||
set -a
|
||||
source .env
|
||||
DEBUG=1
|
||||
set +a
|
||||
|
||||
pm2 stop all
|
||||
docker kill $(docker ps -q)
|
||||
docker rm $(docker ps -a -q)
|
||||
yarn local:dev
|
||||
Loading…
x
Reference in New Issue
Block a user