Verified Commit 2927bc21 authored by Aral Balkan's avatar Aral Balkan
Browse files

Progress on #204

  - Update help
  - Update readme
parent b56086be
......@@ -37,7 +37,7 @@ We exist in part thanks to patronage by people like you. If you share [our visio
- __Includes [Hugo static site generator](#static-site-generation).__
- __[Sync](https://github.com/small-tech/site.js#deployment-live-and-one-time-sync) to deploy__ (uses rsync for quick deployments. Can [sync on changes](https://github.com/small-tech/site.js#deployment-live-and-one-time-sync) and be used for live blogging).
- __[Sync](https://github.com/small-tech/site.js#sync) to deploy__ (uses rsync for quick deployments). Can also [Live Sync](https://github.com/small-tech/site.js#deployment-live-and-one-time-sync) for live blogging, etc.
- __Has privacy-respecting [ephemeral statics](#ephemeral-statistics)__. Gives you insight into how your site is being used, not into the people using it.
......@@ -301,21 +301,20 @@ Use a service like [ngrok](https://ngrok.com/) (Pro+) to point a custom domain n
When you start your server, it will run as a regular process. It will not be restarted if it crashes or if you exit the foreground process or restart the computer.
### Deployment (live and one-time sync)
### Deployment
#### Sync
Site.js can also help you when you want to deploy your site to your live server with its sync feature. You can even have Site.js watch for changes and sync them to your server in real-time (e.g., if you want to live blog something or want to keep a page updated with local data you’re collecting from a sensor):
Site.js can help you deploy your site to your live server with its sync feature.
```shell
$ site my-demo --sync-to=my-demo.site
```
The above command will start a local development server at _https://localhost_. Additionally, it will watch the folder _my-demo_ for changes and sync any changes to its contents via rsync over ssh to the host _my-demo.site_.
The above command will:
If don’t want Site.js to start a server and you want to perform just a one-time sync, use the `--exit-on-sync` flag.
```shell
$ site my-demo --sync-to=my-demo.site --exit-on-sync
```
1. Generate any Hugo content that might need to be generated.
2. Sync your site from the local _my-demo_ folder via rsync over ssh to the host _my-demo.site_.
Without any customisations, the sync feature assumes that your account on your remote server has the same name as your account on your local machine and that the folder you are watching (_my-demo_, in the example above) is located at _/home/your-account/my-demo_ on the remote server. Also, by default, the contents of the folder will be synced, not the folder itself. You can change these defaults by specifying a full-qualified remote connection string as the `--sync-to` value.
......@@ -331,21 +330,28 @@ For example:
$ site my-folder --sync-to=someOtherAccount@my-demo.site:/var/www
```
If you want to sync a different folder to the one you’re serving or if you’re running a proxy server (or if you just want to be as explicit as possible about your intent) you can use the `--sync-from` option to specify the folder to sync:
If you want to sync not the folder’s contents but the folder itself, use the `--sync-folder-and-contents` flag. e.g.,
```shell
$ site :1313 --sync-from=public --sync-to=my-demo.site
$ site my-local-folder --sync-to=me@my.site:my-remote-folder --sync-folder-and-contents
```
(The above command will start a proxy server that forwards requests to and responses from http://localhost to https://localhost and sync the folder called `public` to the host `my-demo.site`.)
The above command will result in the following directory structure on the remote server: _/home/me/my-remote-folder/my-local-folder_. It also demonstrates that if you specify a relative folder, Site.js assumes you mean the folder exists in the home directory of the account on the remote server.
If you want to sync not the folder’s contents but the folder itself, use the `--sync-folder-and-contents` flag. e.g.,
#### Live Sync
With the Live Sync feature, you can have Site.js watch for changes to your content and sync them to your server in real-time (e.g., if you want to live blog something or want to keep a page updated with local data you’re collecting from a sensor).
To start a live sync server, provide the `--live-sync` flag to your sync request.
For example:
```shell
$ site my-local-folder --sync-to=me@my.site:my-remote-folder --sync-folder-and-contents
$ site my-demo --sync-to=my-demo.site --live-sync
```
The above command will result in the following directory structure on the remote server: _/home/me/my-remote-folder/my-local-folder_. It also demonstrates that if you specify a relative folder, Site.js assumes you mean the folder exists in the home directory of the account on the remote server.
The above command will start a local development server at _https://localhost_. Additionally, it will watch the folder _my-demo_ for changes and sync any changes to its contents via rsync over ssh to the host _my-demo.site_.
### Production
......@@ -515,7 +521,7 @@ If `command` is omitted, behaviour defaults to `serve`.
- `--sync-from`: The folder to sync from (only relevant if `--sync-to` is specified).
- `--exit-on-sync`: Exit once the first sync has occurred (only relevant if `--sync-to` is specified). Useful in deployment scripts.
- `--live-sync`: Watch for changes and live sync them to a remote server (only relevant if `--sync-to` is specified).
- `--sync-folder-and-contents`: Sync folder and contents (default is to sync the folder’s contents only).
......@@ -542,16 +548,11 @@ When you `serve` a site at `@hostname` or use the `enable` command, globally-tru
| Serve folder demo on port 666 | site serve demo @localhost:666 |
| Proxy localhost:1313 to https://localhost*| site :1313 |
| | site serve :1313 @localhost:443 |
| Serve current folder, sync it to my.site* | site --sync-to=my.site |
| | site serve . @localhost:443 --sync-to=my.site |
| Serve demo folder, sync it to my.site | site serve demo --sync-to=my.site |
| Ditto, but use account me on my.site | site serve demo --sync-to=me@my.site |
| Ditto, but sync to remote folder ~/www | site serve demo --sync-to=me@my.site:www |
| Ditto, but specify absolute path | site serve demo --sync-to=me@my.site:/home/me/www |
| Sync current folder, proxy localhost:1313 | site serve :1313 --sync-from=. --sync-to=my.site |
| Sync current folder to my.site and exit | site --sync-to=my.site --exit-on-sync |
| Sync demo folder to my.site and exit* | site demo --sync-to=my.site --exit-on-sync |
| | site --sync-from=demo --sync-to=my.site --exit-on-sync |
| Sync demo folder to my.site | site demo --sync-to=my.site |
| Ditto, but use account me on my.site | site demo --sync-to=me@my.site |
| Ditto, but sync to remote folder ~/www | site demo --sync-to=me@my.site:www |
| Ditto, but specify absolute path | site demo --sync-to=me@my.site:/home/me/www |
| Live sync current folder to my.site | site --sync-to=my.site --live-sync |
### Stage and deploy using globally-trusted Let’s Encrypt certificates
......@@ -585,7 +586,6 @@ When you `serve` a site at `@hostname` or use the `enable` command, globally-tru
| ----------------------------------------- | ------------------------------------------------------------- |
| Check for updates and update if found | site update |
\* _Alternative, equivalent forms listed (some commands have shorthands)._
## Native support for an Evergreen Web
......
......@@ -73,7 +73,7 @@ class Help {
const optionSyncTo = option('sync-to')
const optionEnsureCanSync = option('ensure-can-sync')
const optionExitOnSync = option('exit-on-sync')
const optionLiveSync = option('live-sync')
const optionSyncFolderAndContents = option('sync-folder-and-contents')
// Black right-pointing triangle (U+25B6)
......@@ -139,9 +139,9 @@ class Help {
For ${commandServe} command:
${optionSyncTo}\t\t\tThe host to sync to.
${optionSyncFrom}\t\t\tThe folder to sync from (only relevant if ${optionSyncTo} is specified).
${optionExitOnSync}\t\tExit once the first sync has occurred. Useful in deployment scripts.
${optionSyncTo}\t\t\tThe host to sync to (other sync options only relevant if this is supplied).
${optionSyncFrom}\t\t\tThe folder to sync from.
${optionLiveSync}\t\t\tWatch for changes and live sync them to a remote server.
${optionSyncFolderAndContents}\tSync local folder and contents (default is to sync the folder’s contents only).
For ${commandEnable} command:
......@@ -164,20 +164,12 @@ class Help {
• Proxy ${argument('localhost:1313')} ⇄ https://localhost\t${prompt} ${appName} ${argument(':1313')}
(shorthand and full)\t\t\t${prompt} ${appName} ${commandServe} ${argument(':1313')} ${argument('@localhost:443')}
${ this.isWindows ? '' : `
• Serve current folder, sync it to ${argument('my.site')}\t${prompt} ${appName} ${optionSyncTo}=${argument('my.site')}
(shorthand and full)\t\t\t${prompt} ${appName} ${commandServe} ${argument('.')} ${argument('@localhost:443')} ${optionSyncTo}=${argument('my.site')}
• Sync ${argument('demo')} folder to ${argument('my.site')}\t\t${prompt} ${appName} ${argument('demo')} ${optionSyncTo}=${argument('my.site')}
• Ditto, but use account ${argument('me')} on ${argument('my.site')}\t${prompt} ${appName} ${argument('demo')} ${optionSyncTo}=${argument('me@my.site')}
• Ditto, but sync to remote folder ${argument('~/www')}\t${prompt} ${appName} ${argument('demo')} ${optionSyncTo}=${argument('me@my.site:www')}
• Ditto, but specify absolute path\t\t${prompt} ${appName} ${argument('demo')} ${optionSyncTo}=${argument('me@my.site:/home/me/www')}
• Serve ${argument('demo')} folder, sync it to ${argument('my.site')}\t${prompt} ${appName} ${commandServe} ${argument('demo')} ${optionSyncTo}=${argument('my.site')}
• Ditto, but use account ${argument('me')} on ${argument('my.site')}\t${prompt} ${appName} ${commandServe} ${argument('demo')} ${optionSyncTo}=${argument('me@my.site')}
• Ditto, but sync to remote folder ${argument('~/www')}\t${prompt} ${appName} ${commandServe} ${argument('demo')} ${optionSyncTo}=${argument('me@my.site:www')}
• Ditto, but specify absolute path\t\t${prompt} ${appName} ${commandServe} ${argument('demo')} ${optionSyncTo}=${argument('me@my.site:/home/me/www')}
• Sync current folder, proxy ${argument('localhost:1313')}\t${prompt} ${appName} ${commandServe} ${argument(':1313')} ${optionSyncFrom}=${argument('.')} ${optionSyncTo}=${argument('my.site')}
• Sync current folder to ${argument('my.site')} and exit\t${prompt} ${appName} ${optionSyncTo}=${argument('my.site')} ${optionExitOnSync}
• Sync ${argument('demo')} folder to ${argument('my.site')} and exit\t${prompt} ${appName} ${argument('demo')} ${optionSyncTo}=${argument('my.site')} ${optionExitOnSync}
(alternative forms)\t\t\t${prompt} ${appName} ${optionSyncFrom}=${argument('demo')} ${optionSyncTo}=${argument('my.site')} ${optionExitOnSync}
• Live Sync current folder to ${argument('my.site')} \t${prompt} ${appName} ${optionSyncTo}=${argument('my.site')} ${optionLiveSync}
`}${ this.systemdExists ? `
${heading('Stage and deploy using globally-trusted Let’s Encrypt certificates:')}
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment