From dddde131ff5831822a6f0a1ac0b6c5fbf4ea9ad6 Mon Sep 17 00:00:00 2001 From: lovasoa Date: Sun, 11 Aug 2024 15:20:58 +0200 Subject: [PATCH] improve download instructions in tutorial --- .../your-first-sql-website/index.sql | 23 ++++++- .../tutorial-install-any.md | 21 ++++++ .../tutorial-install-macos.md | 17 +++++ .../tutorial-install-windows.md | 14 ++++ .../your-first-sql-website/tutorial.md | 69 ++++++------------- 5 files changed, 93 insertions(+), 51 deletions(-) create mode 100644 examples/official-site/your-first-sql-website/tutorial-install-any.md create mode 100644 examples/official-site/your-first-sql-website/tutorial-install-macos.md create mode 100644 examples/official-site/your-first-sql-website/tutorial-install-windows.md diff --git a/examples/official-site/your-first-sql-website/index.sql b/examples/official-site/your-first-sql-website/index.sql index 076fa99f..8d3ceb65 100644 --- a/examples/official-site/your-first-sql-website/index.sql +++ b/examples/official-site/your-first-sql-website/index.sql @@ -3,12 +3,24 @@ select 'http_header' as component, select 'dynamic' as component, properties FROM example WHERE component = 'shell' LIMIT 1; +set is_windows = COALESCE($is_windows, sqlpage.header('user-agent') like '%windows%'); +set is_linux = COALESCE($is_linux, sqlpage.header('user-agent') like '%x11; linux%'); +set is_macos = COALESCE($is_macos, sqlpage.header('user-agent') like '%macintosh%'); + SELECT 'hero' as component, 'Your first SQL Website' as title, 'Let''s create your first website in SQL together, from downloading SQLPage to connecting it to your database, to making a web app' as description, 'https://upload.wikimedia.org/wikipedia/commons/thumb/c/c4/Backlit_keyboard.jpg/1024px-Backlit_keyboard.jpg' as image, - 'https://datapage.app' as link, - '... or just put your app online now. Try DataPage !' as link_text; + 'https://github.com/lovasoa/SQLpage/releases'|| case + when $is_windows then '/latest/download/sqlpage-windows.zip' + when $is_linux then '/latest/download/sqlpage-linux.tgz' + else '' + end as link, + 'Download SQLPage' || case + when $is_windows then ' for Windows' + when $is_linux then ' for Linux' + else '' + end as link_text; SELECT 'alert' as component, 'Afraid of the setup ? Do it the easy way !' as title, @@ -27,4 +39,11 @@ SELECT 'alert' as component, 'https://www.youtube.com/watch?v=9NJgH_-zXjY' AS link, 'Watch the introduction video' as link_text; +select 'text' as component, sqlpage.read_file_as_text(printf('your-first-sql-website/tutorial-install-%s.md', + case + when $is_windows then 'windows' + when $is_macos then 'macos' + else 'any' + end +)) as contents_md, 'download' as id; select 'text' as component, sqlpage.read_file_as_text('your-first-sql-website/tutorial.md') as contents_md; \ No newline at end of file diff --git a/examples/official-site/your-first-sql-website/tutorial-install-any.md b/examples/official-site/your-first-sql-website/tutorial-install-any.md new file mode 100644 index 00000000..6085a609 --- /dev/null +++ b/examples/official-site/your-first-sql-website/tutorial-install-any.md @@ -0,0 +1,21 @@ +# Download SQLPage: the SQL website framework + +SQLPage is a small executable file that will take requests to your website, execute the SQL files you write, +and render the database responses as nice web pages. + +[Download the latest SQLPage](https://github.com/lovasoa/SQLpage/releases) for your operating system. +In the _release assets_ section, you will find files named `sqlpage-windows.zip`, `sqlpage-linux.tgz`, and `sqlpage-macos.tgz`. +Download the one that corresponds to your operating system, and extract the executable file from the archive. + +> **Note**: On Mac OS, Apple blocks the execution of downloaded files by default. The easiest way to run SQLPage is to use [Homebrew](https://brew.sh). + +> **Note**: Advanced users can alternatively install SQLPage using: +> - [docker](https://hub.docker.com/repository/docker/lovasoa/sqlpage/general) (docker images are also available for ARM, making it easy to run SQLPage on a Raspberry Pi, for example), +> - [brew](https://formulae.brew.sh/formula/sqlpage) (the easiest way to install SQLPage on Mac OS), +> - [nix](https://search.nixos.org/packages?channel=unstable&show=sqlpage) (declarative package management for reproducible deployments), +> - [scoop](https://scoop.sh/#/apps?q=sqlpage&id=305b3437817cd197058954a2f76ac1cf0e444116) (a command-line installer for Windows), +> - or [cargo](https://crates.io/crates/sqlpage) (the Rust package manager). + +You can also find the source code of SQLPage on [GitHub](https://github.com/lovasoa/SQLpage), [install rust](https://www.rust-lang.org/tools/install) on your computer, and compile it yourself with `cargo install sqlpage`. + +See the instructions for [MacOS](?is_macos=1#download), or for [Windows](?is_windows=1#download). diff --git a/examples/official-site/your-first-sql-website/tutorial-install-macos.md b/examples/official-site/your-first-sql-website/tutorial-install-macos.md new file mode 100644 index 00000000..bbabf5e8 --- /dev/null +++ b/examples/official-site/your-first-sql-website/tutorial-install-macos.md @@ -0,0 +1,17 @@ +# Download SQLPage for Mac OS + +On Mac OS, Apple blocks the execution of downloaded files by default. The easiest way to run SQLPage is to use [Homebrew](https://brew.sh). +Open a terminal and run the following commands: + +```sh +/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)" +brew install sqlpage +sqlpage +``` + +> **Note**: Advanced users can alternatively install SQLPage using +> [docker](https://hub.docker.com/repository/docker/lovasoa/sqlpage/general), +> [nix](https://search.nixos.org/packages?channel=unstable&show=sqlpage), +> or [cargo](https://crates.io/crates/sqlpage). + +> **Not on Mac OS?** See the instructions for [Windows](?is_windows=1#download), or for [Other Systems](?is_macos=0#download). \ No newline at end of file diff --git a/examples/official-site/your-first-sql-website/tutorial-install-windows.md b/examples/official-site/your-first-sql-website/tutorial-install-windows.md new file mode 100644 index 00000000..8285d202 --- /dev/null +++ b/examples/official-site/your-first-sql-website/tutorial-install-windows.md @@ -0,0 +1,14 @@ +# Download the SQLPage executable for Windows + +SQLPage offers a small executable file (`sqlpage.exe`) that will take requests to your website, +execute the SQL files you write, and render the database responses as nice web pages. + +[Download the latest SQLPage for Windows](https://github.com/lovasoa/SQLpage/releases/latest/download/sqlpage-windows.zip). +Download the file, and extract the executable file from the zip archive. + +> **Note**: Advanced users can alternatively install SQLPage using +> [docker](https://hub.docker.com/repository/docker/lovasoa/sqlpage/general), +> [scoop](https://scoop.sh/#/apps?q=sqlpage&id=305b3437817cd197058954a2f76ac1cf0e444116), +> or [cargo](https://crates.io/crates/sqlpage). + +> **Not on Windows?** See the instructions for [Mac OS](?is_macos=1#download), or for [Other Systems](?is_windows=0#download). \ No newline at end of file diff --git a/examples/official-site/your-first-sql-website/tutorial.md b/examples/official-site/your-first-sql-website/tutorial.md index 6589e0b4..ad7abbc6 100644 --- a/examples/official-site/your-first-sql-website/tutorial.md +++ b/examples/official-site/your-first-sql-website/tutorial.md @@ -1,19 +1,3 @@ -# Download SQLPage: the SQL website framework - -SQLPage is a small executable file that will take requests to your website, execute the SQL files you write, -and render the database responses as nice web pages. - -[Download the latest SQLPage](https://github.com/lovasoa/SQLpage/releases) for your operating system. -In the _release assets_ section, you will find files named `sqlpage-windows.zip`, `sqlpage-linux.tgz`, and `sqlpage-macos.tgz`. -Download the one that corresponds to your operating system, and extract the executable file from the archive. - -> **Note**: Advanced users can alternatively install SQLPage using -> [docker](https://hub.docker.com/repository/docker/lovasoa/sqlpage/general), -> [brew](https://formulae.brew.sh/formula/sqlpage), -> [nix](https://search.nixos.org/packages?channel=unstable&show=sqlpage), -> [scoop](https://scoop.sh/#/apps?q=sqlpage&id=305b3437817cd197058954a2f76ac1cf0e444116), -> or [cargo](https://crates.io/crates/sqlpage). - # Building your website locally Create a folder on your computer where you will store all contents related to your sql website. @@ -161,38 +145,25 @@ Here is a screenshot of the final result: To go further, have a look at [the examples section of our Github repository](https://github.com/lovasoa/SQLpage/tree/main/examples). -# Deploy your SQLPage website online - -If you want to make your SQLPage website accessible online for everyone to browse, you can deploy it to a VPS (Virtual Private Server). To get started, sign up for a VPS provider of your choice. Some popular options include: AWS EC2, DigitalOcean, Linode, Hetzner. - -Once you have signed up with a VPS provider, create a new VPS instance. The steps may vary depending on the provider, but generally, you will need to: - -1. Choose the appropriate server type and specifications. SQLPage uses very few resources, so you should be fine with the cheaper options. -2. Set up SSH access. - -Once your VPS instance is up and running, you can connect to it using SSH. The provider should provide you with the necessary instructions on how to connect via SSH. - -For example, if you are using a Linux or macOS terminal, you can use the following command: -`ssh username@your-vps-ip-address` - -### Transfer your SQLPage website files to the VPS - -For example, if you are using SCP, you can run the following command from your local computer, replacing the placeholders with your own information: - -`scp -r /path/to/your/sqlpage/folder username@your-vps-ip-address:/path/to/destination` - -### Run SQLPage on the server - -Once your SQLPage website files are on the server, you can run SQLPage on the server, just like you did on your local computer. Download the SQLPage for linux binary and upload it to your server. - -Then, run the following command on your server: - -`./sqlpage` - -To access your website, enter the address of your VPS in your address bar, followed by the port on which SQLPage runs. For instance: http://123.123.123.123:8080. - -For production use, you should: +# Deploy your SQLPage website online -- run SQLPage as a service, using a tool like [docker](https://docs.docker.com/engine/reference/run/) or [systemd](https://linuxhandbook.com/create-systemd-services/). -- [use a reverse proxy like _nginx_](./nginx.sql) to improve security and performance, or to configure multiple websites on the same server. +### Using DataPage.app +To deploy your SQLPage website online, the easiest way is to use [DataPage.app](https://datapage.app), +a managed hosting service for SQLPage websites maintained by the same people who develop SQLPage. +Just create an account, and follow the instructions to upload your website to our servers. It will be live in seconds! + +### Manually +If you prefer to host your website yourself, you can use a cloud provider or a VPS provider. You will need to: +- Configure domain name resolution to point to your server +- Open the port you are using (8080 by default) in your server's firewall +- [Setup docker](https://github.com/lovasoa/SQLpage?tab=readme-ov-file#with-docker) or another process manager such as [systemd](https://github.com/lovasoa/SQLpage/blob/main/sqlpage.service) to start SQLPage automatically when your server boots and to keep it running +- Optionnally, [setup a reverse proxy](nginx.sql) to avoid exposing SQLPage directly to the internet +- Optionnally, setup a TLS certificate to enable HTTPS +- Configure connection to a cloud database or a database running on your server in [`sqlpage.json`](https://github.com/lovasoa/SQLpage/blob/main/configuration.md#configuring-sqlpage) + +# Go further + +- Check out [learnsqlpage.com](https://learnsqlpage.com) by Nick Antonaccio for an in-depth tutorial with many examples +- Read the [SQLPage documentation](/documentation.sql) to learn about all the components available in SQLPage +- Join the [SQLPage community](https://github.com/lovasoa/SQLpage/discussions) to ask questions and share your projects \ No newline at end of file