Skip to content

Commit 6c7df80

Browse files
kokokuokokokuo
authored
Merge pull request #274 from cyyeh/feature/update-doc
Add deployment guides and examples link in homepage
2 parents b3d73ed + e3b2698 commit 6c7df80

File tree

5 files changed

+526
-1
lines changed

5 files changed

+526
-1
lines changed

‎packages/doc/docs/deployment/flydotio.mdx‎

Lines changed: 214 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,214 @@
1+
# Fly.io
2+
3+
In this step-by-step guide, we'll guide you how to deploy your VulcanSQL project to [Fly.io](https://fly.io/).
4+
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),
5+
which is a great deployment option for side-projects.
6+
7+
## Step 1: Install Fly.io
8+
9+
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.
10+
You should install the version that's appropriate for your operating system.
11+
12+
After successfully installed `flyctl`, you should see the following message if you type `fly` in the terminal:
13+
14+
```
15+
% fly
16+
This is flyctl, the Fly.io command line interface.
17+
18+
Here's a few commands to get you started:
19+
fly launch Launch a new application
20+
fly apps Create and manage apps
21+
fly postgres Create and manage Postgres databases
22+
fly mysql Create and manage PlanetScale MySQL databases
23+
fly redis Create and manage Upstash Redis databases
24+
fly machines Create and manage individual Fly.io machines
25+
26+
If you need help along the way:
27+
fly help Display a complete list of commands
28+
fly help <command> Display help for a specific command, e.g. 'fly help launch'
29+
30+
Visit https://fly.io/docs for additional documentation & guides
31+
```
32+
33+
## Step 2: Login to Fly.io
34+
35+
**Signup**
36+
37+
If this is your first time setting up Fly.io, please execute the following command in the terminal:
38+
39+
```bash
40+
fly auth signup
41+
```
42+
43+
After successfully sign up in Fly.io, you should see the following message in the terminal:
44+
45+
```
46+
Waiting for session... Done
47+
successfully logged in as xxxxx@xxx
48+
```
49+
50+
For more detailed introduction on how to sign up, you can [read more here](https://fly.io/docs/hands-on/sign-up/).
51+
52+
**Login**
53+
54+
If you already have a Fly.io account, please execute the following command in the terminal:
55+
56+
```bash
57+
fly auth login
58+
```
59+
60+
After successfully login in Fly.io, you should see the following message in the terminal:
61+
62+
```
63+
Waiting for session... Done
64+
successfully logged in as xxxxx@xxx
65+
```
66+
67+
For more detailed introduction on how to sign in, you can [read more here](https://fly.io/docs/hands-on/sign-in/).
68+
69+
## Step 3: Package your VulcanSQL API Server
70+
71+
In this guide, we'll deploy the Docker version of your VulcanSQL API Server. So please execute the following command in the terminal:
72+
73+
```bash
74+
vulcan package -o docker
75+
```
76+
77+
After executing the command, you'll see a message shown like below and a new directory `dist` in the project directory.
78+
79+
```bash
80+
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.
81+
✔ Package successfully.
82+
```
83+
84+
The directory structure of `dist` is as following:
85+
86+
```
87+
dist
88+
├── Dockerfile
89+
├── config.json
90+
├── index.js
91+
├── package.json
92+
└── result.json
93+
```
94+
95+
:::caution
96+
External resources and configurations, such as `profiles.yaml`, are not copied to the `dist` folder.
97+
You'll need to copy them manually. We strongly recommend using a separate profile instead of the one used for development.
98+
99+
After copying `profiles.yaml` into the `dist` folder, you should also add one line in `Dockerfile` as following:
100+
101+
```shell
102+
.
103+
.
104+
.
105+
FROM node:16-bullseye-slim
106+
WORKDIR /usr/app
107+
COPY --from=build /usr/app /usr/app
108+
COPY config.json .
109+
COPY index.js .
110+
COPY result.json .
111+
# add the line below
112+
COPY profiles.yaml .
113+
ENV NODE_ENV production
114+
115+
CMD [ "node", "index.js" ]
116+
```
117+
118+
**Notes: if you have [multiple profiles](../references/data-source-profile#define-profile-in-independent-yaml-files),
119+
you should copy them into the dist folder and add them all in the Dockerfile.**
120+
:::
121+
122+
## Step 4: Setup Fly.io deployment config
123+
124+
Please execute the following command in the terminal in order to generate a Fly.io deployment config `fly.toml`:
125+
126+
```shell
127+
fly launch
128+
```
129+
130+
After executing the command, Fly.io would ask you several questions such as:
131+
1. Chooese an app name
132+
2. Select organization
133+
3. Choose a region for deployment
134+
4. Would you like to set up a Postgresql database now?
135+
5. Would you like to set up an Upstash Redis database now?
136+
6. Would you like to deploy now?
137+
138+
After answering these questions, you will see `fly.toml` in the `dist` folder and the content is similar to this:
139+
140+
```toml
141+
# fly.toml app configuration file generated for xxxxx on 2023-07-13T22:40:54+08:00
142+
#
143+
# See https://fly.io/docs/reference/configuration/ for information about how to use this file.
144+
#
145+
146+
app = "xxxxx"
147+
primary_region = "bos"
148+
149+
[http_service]
150+
internal_port = 3000
151+
force_https = true
152+
auto_stop_machines = false
153+
auto_start_machines = false
154+
min_machines_running = 1
155+
processes = ["app"]
156+
```
157+
158+
:::info
159+
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.
160+
:::
161+
162+
For more detailed introduction on how to launch your app, you can [read more here](https://fly.io/docs/hands-on/launch-app/).
163+
164+
## Step 5: Deploy to Fly.io
165+
166+
Finally, you can execute the following command in the terminal to deploy your VulcanSQL API Server and share it with the world!
167+
168+
```shell
169+
fly deploy
170+
```
171+
172+
After successfully deploying the app, you should see the following message in the terminal:
173+
174+
```shell
175+
Watch your app at https://fly.io/apps/xxxx/monitoring
176+
177+
Visit your newly deployed app at https://xxxxx/
178+
```
179+
180+
:::info
181+
You can read more here regarding to [deployment via Dockerfile](https://fly.io/docs/languages-and-frameworks/dockerfile/).
182+
:::
183+
184+
Congratulations! Now your VulcanSQL app is on the cloud and is ready to be shared to the world!
185+
186+
:::info
187+
If you need to clean up the resources on Fly.io, you can [read the documentation here](https://fly.io/docs/flyctl/destroy/).
188+
:::
189+
190+
## Step 6: (Optional) Deploy your VulcanSQL API Catalog Server
191+
192+
If you need to deploy API Catalog Server, you should execute the following command in the terminal:
193+
194+
```shell
195+
vulcan package -t catalog-server -o docker
196+
```
197+
198+
:::caution
199+
The folder generated by the command is also called `dist`, so if you had executed the command of packaging
200+
API server, you should rename the `dist` folder generated previously to prevent from being overwritten.
201+
:::
202+
203+
Then, you should modify `API_BASE_URL` to the URL of your VulcanSQL API Server you just deployed in Dockerfile:
204+
205+
```dockerfile
206+
ENV API_BASE_URL [URL of VulcanSQL API Server]
207+
```
208+
209+
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:
210+
211+
```
212+
fly launch
213+
fly deploy
214+
```

‎packages/doc/docs/deployment/gcp-app-engine.mdx‎

Lines changed: 143 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,143 @@
1+
# GCP: App Engine
2+
3+
In this step-by-step guide, we'll guide you how to deploy your VulcanSQL project to Google Cloud Platform(GCP)
4+
using [App Engine](https://cloud.google.com/appengine). It's an application platform for developers to build monolithic
5+
server-side rendered websites.
6+
7+
:::info
8+
For more detailed information of the deployment process, you can [read more here](https://cloud.google.com/appengine/docs/standard/nodejs/runtime).
9+
:::
10+
11+
## Step 1: Install and setup the Google Cloud CLI
12+
13+
Before you begin to use Cloud Run on GCP, you need to do several things:
14+
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.
15+
2. [Make sure the billing is enabled for your Google Cloud project.](https://cloud.google.com/billing/docs/how-to/verify-billing-enabled#console)
16+
3. [Install](https://cloud.google.com/sdk/docs/install) the Google Cloud CLI.
17+
4. Initialize the gcloud CLI with the following command:
18+
```shell
19+
gcloud init
20+
```
21+
5. You can set the default project for your Cloud Run service with the following command:
22+
```shell
23+
gcloud config set project [PROJECT_ID]
24+
```
25+
26+
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).
27+
28+
## Step 2: Package your VulcanSQL API Server
29+
30+
In this guide, we'll deploy your VulcanSQL API Server without Docker. So please execute the following command in the terminal:
31+
32+
```bash
33+
vulcan package --output node
34+
```
35+
36+
After executing the command, you'll see a message shown like below and a new directory `dist` in the project directory.
37+
38+
```bash
39+
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
40+
✔ Package successfully.
41+
```
42+
43+
The directory structure of `dist` is as following:
44+
45+
```
46+
dist
47+
├── config.json
48+
├── index.js
49+
├── package.json
50+
└── result.json
51+
```
52+
53+
:::caution
54+
External resources and configurations, such as `profiles.yaml`, are not copied to the `dist` folder.
55+
You'll need to copy them manually. We strongly recommend using a separate profile instead of the one used for development.
56+
:::
57+
58+
## Step 3: Deploy to App Engine from source
59+
60+
Now we need to do several things before deploying the app to App Engine:
61+
62+
**1. Add `port:8080` to `config.json`**
63+
64+
Since App Engine accepts network traffic with the [port 8080](https://cloud.google.com/appengine/docs/flexible/custom-runtimes/build#listening_to_port_8080).
65+
66+
**2. Change the filename of `index.js` to `server.js` and also in `package.json`**
67+
68+
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.
69+
70+
**3. Create a new file `app.yaml` and fill in the following content**
71+
72+
```yaml
73+
runtime: nodejs
74+
env: flex
75+
runtime_config:
76+
operating_system: "ubuntu22"
77+
runtime_version: "18"
78+
```
79+
80+
Finally, you can run the following command to deploy your app in the terminal:
81+
82+
```shell
83+
gcloud app deploy
84+
```
85+
86+
After successfully deploying your VulcanSQL app, you'll see the similar message in the terminal:
87+
88+
```
89+
Deployed service [default] to [https://cannerflow-286003.uw.r.appspot.com]
90+
91+
You can stream logs from the command line by running:
92+
$ gcloud app logs tail -s default
93+
94+
To view your application in the web browser run:
95+
$ gcloud app browse
96+
```
97+
98+
Congratulations! Now your VulcanSQL app is on the cloud and is ready to be shared to the world!
99+
100+
:::info
101+
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).
102+
:::
103+
104+
## Step 4: (Optional) Deploy your VulcanSQL API Catalog Server
105+
106+
If you need to deploy API Catalog Server, you should execute the following command in the terminal:
107+
108+
```shell
109+
vulcan package -t catalog-server
110+
```
111+
112+
:::caution
113+
The folder generated by the command is also called `dist`, so if you had executed the command of packaging
114+
API server, you should rename the `dist` folder generated previously to prevent from being overwritten.
115+
:::
116+
117+
Now we need to do several things before deploying the app to App Engine:
118+
119+
**1. Add `"config": {"port": 8080}` to `config.json`**
120+
121+
Since App Engine accepts network traffic with the [port 8080](https://cloud.google.com/appengine/docs/flexible/custom-runtimes/build#listening_to_port_8080).
122+
123+
**2. Change the filename of `index.js` to `server.js` and also in `package.json`**
124+
125+
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.
126+
127+
**3. Create a new file `app.yaml` and fill in the following content**
128+
129+
```yaml
130+
runtime: nodejs
131+
env: flex
132+
runtime_config:
133+
operating_system: "ubuntu22"
134+
runtime_version: "18"
135+
env_variables:
136+
VULCAN_SQL_HOST: [Your VulcanSQL API Server URL]
137+
```
138+
139+
Finally, you execute the same Google Cloud CLI commands used in the step 3 in the terminal:
140+
141+
```
142+
gcloud app deploy
143+
```

0 commit comments

Comments
 (0)