diff --git a/packages/doc/docs/deployment/flydotio.mdx b/packages/doc/docs/deployment/flydotio.mdx new file mode 100644 index 00000000..4d49aa37 --- /dev/null +++ b/packages/doc/docs/deployment/flydotio.mdx @@ -0,0 +1,214 @@ +# Fly.io + +In this step-by-step guide, we'll guide you how to deploy your VulcanSQL project to [Fly.io](https://fly.io/). +Fly.io is a developer friendly service to deploy your apps. Besides, it has [free allowances](https://fly.io/docs/about/pricing/#em-free-allowances-em), +which is a great deployment option for side-projects. + +## Step 1: Install Fly.io + +Please go to [this website](https://fly.io/docs/hands-on/install-flyctl/) for installing `flyctl`, which is a command-line utility that lets you work with Fly.io. +You should install the version that's appropriate for your operating system. + +After successfully installed `flyctl`, you should see the following message if you type `fly` in the terminal: + +``` +% fly +This is flyctl, the Fly.io command line interface. + +Here's a few commands to get you started: + fly launch Launch a new application + fly apps Create and manage apps + fly postgres Create and manage Postgres databases + fly mysql Create and manage PlanetScale MySQL databases + fly redis Create and manage Upstash Redis databases + fly machines Create and manage individual Fly.io machines + +If you need help along the way: + fly help Display a complete list of commands + fly help Display help for a specific command, e.g. 'fly help launch' + +Visit https://fly.io/docs for additional documentation & guides +``` + +## Step 2: Login to Fly.io + +**Signup** + +If this is your first time setting up Fly.io, please execute the following command in the terminal: + +```bash +fly auth signup +``` + +After successfully sign up in Fly.io, you should see the following message in the terminal: + +``` +Waiting for session... Done +successfully logged in as xxxxx@xxx +``` + +For more detailed introduction on how to sign up, you can [read more here](https://fly.io/docs/hands-on/sign-up/). + +**Login** + +If you already have a Fly.io account, please execute the following command in the terminal: + +```bash +fly auth login +``` + +After successfully login in Fly.io, you should see the following message in the terminal: + +``` +Waiting for session... Done +successfully logged in as xxxxx@xxx +``` + +For more detailed introduction on how to sign in, you can [read more here](https://fly.io/docs/hands-on/sign-in/). + +## Step 3: Package your VulcanSQL API Server + +In this guide, we'll deploy the Docker version of your VulcanSQL API Server. So please execute the following command in the terminal: + +```bash +vulcan package -o docker +``` + +After executing the command, you'll see a message shown like below and a new directory `dist` in the project directory. + +```bash +2023-08-07 08:47:26.246 INFO [CORE] Package successfully, you can go to "dist" folder and run "docker build ." to build the image. +✔ Package successfully. +``` + +The directory structure of `dist` is as following: + +``` +dist +├── Dockerfile +├── config.json +├── index.js +├── package.json +└── result.json +``` + +:::caution +External resources and configurations, such as `profiles.yaml`, are not copied to the `dist` folder. +You'll need to copy them manually. We strongly recommend using a separate profile instead of the one used for development. + +After copying `profiles.yaml` into the `dist` folder, you should also add one line in `Dockerfile` as following: + +```shell +. +. +. +FROM node:16-bullseye-slim +WORKDIR /usr/app +COPY --from=build /usr/app /usr/app +COPY config.json . +COPY index.js . +COPY result.json . +# add the line below +COPY profiles.yaml . +ENV NODE_ENV production + +CMD [ "node", "index.js" ] +``` + +**Notes: if you have [multiple profiles](../references/data-source-profile#define-profile-in-independent-yaml-files), +you should copy them into the dist folder and add them all in the Dockerfile.** +::: + +## Step 4: Setup Fly.io deployment config + +Please execute the following command in the terminal in order to generate a Fly.io deployment config `fly.toml`: + +```shell +fly launch +``` + +After executing the command, Fly.io would ask you several questions such as: +1. Chooese an app name +2. Select organization +3. Choose a region for deployment +4. Would you like to set up a Postgresql database now? +5. Would you like to set up an Upstash Redis database now? +6. Would you like to deploy now? + +After answering these questions, you will see `fly.toml` in the `dist` folder and the content is similar to this: + +```toml +# fly.toml app configuration file generated for xxxxx on 2023-07-13T22:40:54+08:00 +# +# See https://fly.io/docs/reference/configuration/ for information about how to use this file. +# + +app = "xxxxx" +primary_region = "bos" + +[http_service] + internal_port = 3000 + force_https = true + auto_stop_machines = false + auto_start_machines = false + min_machines_running = 1 + processes = ["app"] +``` + +:::info +You can make `auto_stop_machines` to be false, so that you don't need to worry if the machine will hibernate if no one accesses it for a while. +::: + +For more detailed introduction on how to launch your app, you can [read more here](https://fly.io/docs/hands-on/launch-app/). + +## Step 5: Deploy to Fly.io + +Finally, you can execute the following command in the terminal to deploy your VulcanSQL API Server and share it with the world! + +```shell +fly deploy +``` + +After successfully deploying the app, you should see the following message in the terminal: + +```shell +Watch your app at https://fly.io/apps/xxxx/monitoring + +Visit your newly deployed app at https://xxxxx/ +``` + +:::info +You can read more here regarding to [deployment via Dockerfile](https://fly.io/docs/languages-and-frameworks/dockerfile/). +::: + +Congratulations! Now your VulcanSQL app is on the cloud and is ready to be shared to the world! + +:::info +If you need to clean up the resources on Fly.io, you can [read the documentation here](https://fly.io/docs/flyctl/destroy/). +::: + +## Step 6: (Optional) Deploy your VulcanSQL API Catalog Server + +If you need to deploy API Catalog Server, you should execute the following command in the terminal: + +```shell +vulcan package -t catalog-server -o docker +``` + +:::caution +The folder generated by the command is also called `dist`, so if you had executed the command of packaging +API server, you should rename the `dist` folder generated previously to prevent from being overwritten. +::: + +Then, you should modify `API_BASE_URL` to the URL of your VulcanSQL API Server you just deployed in Dockerfile: + +```dockerfile +ENV API_BASE_URL [URL of VulcanSQL API Server] +``` + +Finally, you execute the same Fly.io commands used in the step 4 and step 5 in the terminal, and change any configurations if you need: + +``` +fly launch +fly deploy +``` diff --git a/packages/doc/docs/deployment/gcp-app-engine.mdx b/packages/doc/docs/deployment/gcp-app-engine.mdx new file mode 100644 index 00000000..b2697e17 --- /dev/null +++ b/packages/doc/docs/deployment/gcp-app-engine.mdx @@ -0,0 +1,143 @@ +# GCP: App Engine + +In this step-by-step guide, we'll guide you how to deploy your VulcanSQL project to Google Cloud Platform(GCP) +using [App Engine](https://cloud.google.com/appengine). It's an application platform for developers to build monolithic +server-side rendered websites. + +:::info +For more detailed information of the deployment process, you can [read more here](https://cloud.google.com/appengine/docs/standard/nodejs/runtime). +::: + +## Step 1: Install and setup the Google Cloud CLI + +Before you begin to use Cloud Run on GCP, you need to do several things: +1. In the Google Cloud console, on the [project selector page](https://console.cloud.google.com/projectselector2/home/dashboard), select or create a Google Cloud project. +2. [Make sure the billing is enabled for your Google Cloud project.](https://cloud.google.com/billing/docs/how-to/verify-billing-enabled#console) +3. [Install](https://cloud.google.com/sdk/docs/install) the Google Cloud CLI. +4. Initialize the gcloud CLI with the following command: + ```shell + gcloud init + ``` +5. You can set the default project for your Cloud Run service with the following command: + ```shell + gcloud config set project [PROJECT_ID] + ``` + +For more detailed instructions on how to setup the environment, you can [read more here](https://cloud.google.com/appengine/docs/standard/nodejs/building-app/creating-project). + +## Step 2: Package your VulcanSQL API Server + +In this guide, we'll deploy your VulcanSQL API Server without Docker. So please execute the following command in the terminal: + +```bash +vulcan package --output node +``` + +After executing the command, you'll see a message shown like below and a new directory `dist` in the project directory. + +```bash +2023-08-08 08:59:27.666 INFO [CORE] Package successfully, you can go to "dist" folder and run "npm install && node index.js" to start the server +✔ Package successfully. +``` + +The directory structure of `dist` is as following: + +``` +dist +├── config.json +├── index.js +├── package.json +└── result.json +``` + +:::caution +External resources and configurations, such as `profiles.yaml`, are not copied to the `dist` folder. +You'll need to copy them manually. We strongly recommend using a separate profile instead of the one used for development. +::: + +## Step 3: Deploy to App Engine from source + +Now we need to do several things before deploying the app to App Engine: + +**1. Add `port:8080` to `config.json`** + +Since App Engine accepts network traffic with the [port 8080](https://cloud.google.com/appengine/docs/flexible/custom-runtimes/build#listening_to_port_8080). + +**2. Change the filename of `index.js` to `server.js` and also in `package.json`** + +Since App Engine recognizes [`server.js`](https://cloud.google.com/appengine/docs/standard/nodejs/building-app/writing-web-service#running_the_server_locally) as the entry file. + +**3. Create a new file `app.yaml` and fill in the following content** + +```yaml +runtime: nodejs +env: flex +runtime_config: + operating_system: "ubuntu22" + runtime_version: "18" +``` + +Finally, you can run the following command to deploy your app in the terminal: + +```shell +gcloud app deploy +``` + +After successfully deploying your VulcanSQL app, you'll see the similar message in the terminal: + +``` +Deployed service [default] to [https://cannerflow-286003.uw.r.appspot.com] + +You can stream logs from the command line by running: + $ gcloud app logs tail -s default + +To view your application in the web browser run: + $ gcloud app browse +``` + +Congratulations! Now your VulcanSQL app is on the cloud and is ready to be shared to the world! + +:::info +If you need to clean up the resources on App Engine, you can [read the documentation here](https://cloud.google.com/appengine/docs/standard/python3/building-app/cleaning-up). +::: + +## Step 4: (Optional) Deploy your VulcanSQL API Catalog Server + +If you need to deploy API Catalog Server, you should execute the following command in the terminal: + +```shell +vulcan package -t catalog-server +``` + +:::caution +The folder generated by the command is also called `dist`, so if you had executed the command of packaging +API server, you should rename the `dist` folder generated previously to prevent from being overwritten. +::: + +Now we need to do several things before deploying the app to App Engine: + +**1. Add `"config": {"port": 8080}` to `config.json`** + +Since App Engine accepts network traffic with the [port 8080](https://cloud.google.com/appengine/docs/flexible/custom-runtimes/build#listening_to_port_8080). + +**2. Change the filename of `index.js` to `server.js` and also in `package.json`** + +Since App Engine recognizes [`server.js`](https://cloud.google.com/appengine/docs/standard/nodejs/building-app/writing-web-service#running_the_server_locally) as the entry file. + +**3. Create a new file `app.yaml` and fill in the following content** + +```yaml +runtime: nodejs +env: flex +runtime_config: + operating_system: "ubuntu22" + runtime_version: "18" +env_variables: + VULCAN_SQL_HOST: [Your VulcanSQL API Server URL] +``` + +Finally, you execute the same Google Cloud CLI commands used in the step 3 in the terminal: + +``` +gcloud app deploy +``` diff --git a/packages/doc/docs/deployment/gcp-cloud-run.mdx b/packages/doc/docs/deployment/gcp-cloud-run.mdx new file mode 100644 index 00000000..bd0c8877 --- /dev/null +++ b/packages/doc/docs/deployment/gcp-cloud-run.mdx @@ -0,0 +1,132 @@ +# GCP: Cloud Run + +In this step-by-step guide, we'll guide you how to deploy your VulcanSQL project to Google Cloud Platform(GCP) +using [Cloud Run](https://cloud.google.com/run). It's a service that we can build and deploy containerized apps +written in any language(including Go, Python, Java, Node.js, .Net, and Ruby) on a fully managed platform. + +:::info +For more detailed information of the deployment process, you can [read more here](https://cloud.google.com/run/docs/quickstarts/build-and-deploy/deploy-nodejs-service). +::: + +## Step 1: Install and setup the Google Cloud CLI + +Before you begin to use Cloud Run on GCP, you need to do several things: +1. In the Google Cloud console, on the [project selector page](https://console.cloud.google.com/projectselector2/home/dashboard), select or create a Google Cloud project. +2. [Make sure the billing is enabled for your Google Cloud project.](https://cloud.google.com/billing/docs/how-to/verify-billing-enabled#console) +3. [Install](https://cloud.google.com/sdk/docs/install) the Google Cloud CLI. +4. Initialize the gcloud CLI with the following command: + ```shell + gcloud init + ``` +5. You can set the default project for your Cloud Run service with the following command: + ```shell + gcloud config set project [PROJECT_ID] + ``` + +For more detailed instructions on how to setup the environment, you can [read more here](https://cloud.google.com/run/docs/quickstarts/build-and-deploy/deploy-nodejs-service#before-you-begin). + +## Step 2: Package your VulcanSQL API Server + +In this guide, we'll deploy the Docker version of your VulcanSQL API Server. So please execute the following command in the terminal: + +```bash +vulcan package --output docker +``` + +After executing the command, you'll see a message shown like below and a new directory `dist` in the project directory. + +```bash +2023-08-07 08:47:26.246 INFO [CORE] Package successfully, you can go to "dist" folder and run "docker build ." to build the image. +✔ Package successfully. +``` + +The directory structure of `dist` is as following: + +``` +dist +├── Dockerfile +├── config.json +├── index.js +├── package.json +└── result.json +``` + +:::caution +External resources and configurations, such as `profiles.yaml`, are not copied to the `dist` folder. +You'll need to copy them manually. We strongly recommend using a separate profile instead of the one used for development. + +After copying `profiles.yaml` into the `dist` folder, you should also add one line in `Dockerfile` as following: + +```shell +. +. +. +FROM node:16-bullseye-slim +WORKDIR /usr/app +COPY --from=build /usr/app /usr/app +COPY config.json . +COPY index.js . +COPY result.json . +# add the line below +COPY profiles.yaml . +ENV NODE_ENV production + +CMD [ "node", "index.js" ] +``` + +**Notes: if you have [multiple profiles](../references/data-source-profile#define-profile-in-independent-yaml-files), +you should copy them into the dist folder and add them all in the Dockerfile.** +::: + +## Step 3: Deploy to Cloud Run from source + +Now you can deploy you VulcanSQL app to GCP with the following command: + +```shell +gloud run deploy [YOUR_CLOUDRUN_SERVICE_NAME] --port=3000 --allow-unauthenticated +``` + +:::caution +Important: This quickstart assumes that you have owner or editor roles in the project you are using for the quickstart. +Otherwise, refer to [Cloud Run deployment permissions](https://cloud.google.com/run/docs/reference/iam/roles#additional-configuration), +[Cloud Build permissions](https://cloud.google.com/build/docs/iam-roles-permissions#predefined_roles), and +[Artifact Registry permissions](https://cloud.google.com/artifact-registry/docs/access-control#permissions) for the permissions required. +::: + +After successfully deploy the app, you'll see a similar message in the terminal: + +``` +Service [vulcansql-project] revision [vulcansql-project-00001-mud] has been deployed and is serving 100 percent of traffic. +Service URL: https://vulcansql-project-ggcxvljfba-df.a.run.app +``` + +Congratulations! Now your VulcanSQL app is on the cloud and is ready to be shared to the world! + +:::info +If you need to clean up the resources on Cloud Run, you can [read the documentation here](https://cloud.google.com/run/docs/quickstarts/build-and-deploy/deploy-nodejs-service#clean-up). +::: + +## Step 4: (Optional) Deploy your VulcanSQL API Catalog Server + +If you need to deploy API Catalog Server, you should execute the following command in the terminal: + +```shell +vulcan package -t catalog-server -o docker +``` + +:::caution +The folder generated by the command is also called `dist`, so if you had executed the command of packaging +API server, you should rename the `dist` folder generated previously to prevent from being overwritten. +::: + +Then, you should modify `API_BASE_URL` to the URL of your VulcanSQL API Server you just deployed in Dockerfile: + +```dockerfile +ENV API_BASE_URL [URL of VulcanSQL API Server] +``` + +Finally, you execute the same Google Cloud CLI commands used in the step 3 in the terminal, and change any configurations if you need: + +``` +gloud run deploy [YOUR_CLOUDRUN_SERVICE_NAME] --port=4200 --allow-unauthenticated +``` diff --git a/packages/doc/docusaurus.config.js b/packages/doc/docusaurus.config.js index 13749708..03a39b55 100644 --- a/packages/doc/docusaurus.config.js +++ b/packages/doc/docusaurus.config.js @@ -75,6 +75,11 @@ const config = { position: 'left', label: 'Blog', }, + { + href: 'https://github.com/Canner/vulcan-sql-examples', + position: 'left', + label: 'Examples', + }, { href: 'https://discord.gg/ztDz8DCmG4', position: 'left', @@ -100,12 +105,16 @@ const config = { items: [ { label: 'Getting Started', - to: '/docs/intro', + to: '/docs/get-started/first-api', }, { label: 'Building Data API', to: '/docs/develop/init', }, + { + label: 'Extensions', + to: '/docs/extensions/overview', + }, { label: 'API Catalog & Documentation', to: '/docs/catalog/intro', @@ -118,6 +127,10 @@ const config = { label: 'Deployment and Maintenance', to: '/docs/deployment', }, + { + label: 'References', + to: '/docs/references/project-configurations', + }, ], }, { @@ -140,6 +153,10 @@ const config = { label: 'GitHub', href: 'https://github.com/Canner/vulcan-sql', }, + { + label: 'Examples', + href: 'https://github.com/Canner/vulcan-sql-examples', + }, { label: 'Privacy', href: 'https://cannerdata.com/terms/privacy' diff --git a/packages/doc/sidebars.js b/packages/doc/sidebars.js index 50a71543..ece855ec 100644 --- a/packages/doc/sidebars.js +++ b/packages/doc/sidebars.js @@ -389,6 +389,25 @@ const sidebars = { className: 'sidebar-title', }, 'deployment', + { + type: 'category', + label: 'Cloud Deployment Guides', + link: { type: 'doc', id: 'deployment/flydotio' }, + items: [ + { + type: 'doc', + id: 'deployment/flydotio', + }, + { + type: 'doc', + id: 'deployment/gcp-cloud-run', + }, + { + type: 'doc', + id: 'deployment/gcp-app-engine', + } + ], + }, { type: 'html', value: