|
1 | | -# Quickstart Guide |
| 1 | +# Installation |
2 | 2 |
|
3 | | -A small teaser of what you will have build in a couple of minutes from now: |
| 3 | +To start using Syncano with your project follow the steps: |
4 | 4 |
|
5 | | - |
6 | | - |
7 | | -Tutorial steps: |
8 | | -1. Cloning an example repository with a simple front-end project (a chat app) |
9 | | -2. Syncano CLI installation |
10 | | -3. Signing up and creating a Syncano project |
11 | | -4. Installing a Syncano Socket |
12 | | -5. Configuring the front-end |
13 | | -6. Deploying your application to the cloud |
14 | | - |
15 | | -> You can test the app live at this url: https://production--chat-app.syncano.site/ |
16 | | -
|
17 | | -# Clone the example repository |
18 | | - |
19 | | -First git clone the sample Chat project by going to your terminal application and running: |
20 | | - |
21 | | -```sh |
22 | | -git clone https://github.com/Syncano-Community/chat-app.git |
23 | | -cd chat-app |
24 | | -``` |
25 | | - |
26 | | -# Install the Syncano CLI |
27 | | - |
28 | | -> **In order to use the Syncano CLI you will have to install the following dependencies:** |
29 | | -* NodeJS greater than [](http://nodejs.org/) |
30 | | -* NPM greater than [](http://npmjs.com/) |
31 | | -* Yarn greater than [](https://yarnpkg.com/en/docs/install) |
| 5 | +## Install the Syncano CLI in your project |
32 | 6 |
|
33 | 7 | The `syncano-cli` is the main tool for setting up and managing your projects on the Syncano Platform. To install it, run: |
34 | 8 |
|
35 | 9 | ```sh |
36 | | -npm install -g syncano-cli |
| 10 | +$ npm install @syncano/cli --save-dev |
37 | 11 | ``` |
38 | 12 |
|
39 | | -# Sign up and create a project |
40 | | -Once the Syncano CLI is installed you can sign up for an account. Run the following command in the root directory of your project: |
| 13 | +## Sign up and create a project |
| 14 | +Once the Syncano CLI is installed you need to sign up for an account. Run the following command in the root directory of your project: |
41 | 15 |
|
42 | 16 | ```sh |
43 | | -syncano-cli init |
| 17 | +$ npx s init |
44 | 18 | ``` |
45 | 19 |
|
| 20 | +> `s` is an alias to `syncano-cli` - you can simply type `syncano-cli` |
| 21 | +> e.g. `npx syncano-cli init` |
| 22 | +
|
46 | 23 | You'll be asked for an `email` and `password` so that we can create an account for you. |
47 | 24 | You'll also be prompted for a project template. Choose the recommended `Hello World` template and press enter. |
48 | 25 |
|
49 | | - |
50 | | - |
51 | | -# Install a Syncano Socket |
| 26 | +## Deploy your project |
52 | 27 |
|
53 | | -Now, we will install the `chat` socket from the `Syncano Registry`. |
54 | | - |
55 | | -> Sockets are modules that enclose a piece of functionality needed for your app. The difference is, that instead of functions they expose endpoints for communication with the server, and emit events so that integrations with other sockets are possible. You can find out more about the Sockets concept in the Sockets Overview section. |
| 28 | +Now it's time to deploy your app to the cloud. To do this, run the following command: |
56 | 29 |
|
57 | 30 | ```sh |
58 | | -syncano-cli add chat |
| 31 | +npx s deploy |
59 | 32 | ``` |
60 | | - |
61 | | - |
62 | | -This command will add a `chat` Socket as a dependency of your project. It has everything that is needed for your chat application front-end to work. By now your `chat-app` project structure should look like this: |
63 | | - |
64 | | - |
65 | 33 |
|
66 | | -> Run `syncano-cli list chat` to view the Socket documentation |
| 34 | +## Ok, but What has just happened!? |
67 | 35 |
|
68 | | -To make sure it has been added correctly, you can open the `/chat-app/syncano/syncano.yml` and see if these lines are present: |
69 | | -> The chat app Socket you installed may have a higher version number |
70 | | -
|
71 | | -```yml |
72 | | -dependencies: |
73 | | - sockets: |
74 | | - chat: |
75 | | - version: 0.0.1 |
76 | | -``` |
77 | | -
|
78 | | -# Configure your front-end |
79 | | -
|
80 | | -The only change you need to make in the code is in the `./web/index.html` file. Open it and replace the `INSTANCE_NAME` with your `Instance` name in the 8th line: |
81 | | - |
82 | | - |
83 | | - |
84 | | - > To find out your Instance name you can run `syncano-cli` command. It will be printed as a `Current Instance`. |
85 | | - |
86 | | -# Deploy your project |
87 | | - |
88 | | -Now it's time to deploy your app. To do this, run the following command: |
| 36 | +You've just deployed you first Syncano backend. Now you can verify what kind of endpoints you can reach on the backend side: |
89 | 37 |
|
90 | 38 | ```sh |
91 | | -syncano-cli hosting add ./web |
| 39 | +npx s list |
92 | 40 | ``` |
93 | | - |
94 | | - |
95 | | -Choose the defaults when prompted and type `y` and press enter when asked `Do you want to sync files now?` |
96 | | - |
97 | | -Your web assets will be published under the url printed by the Syncano CLI. It should have this format: `https://staging--<instance name>.syncano.site/`. Go to this url to see the published project. Open the url in two tabs to experience the realtime in action. |
98 | | - |
99 | | -# Ok, but What has just happened!? |
100 | | - |
101 | | -You have successfully configured and deployed a full stack, realtime chat application. Well done! |
102 | | - |
103 | | -How did it happen? Here's a quick rundown: |
104 | 41 |
|
105 | | -1. When running `syncano-cli add chat` you have connected to `Syncano Registry` which contains components that you can integrate into your app. Run `syncano-cli search [term]` to discover more Sockets. |
106 | | -2. The `chat` Socket was added as a dependency in the `syncano.yml` file. All the dependencies installed from the `Syncano Registry` will be present in this file |
107 | | -3. By providing the `instance_name` in the `index.html` you simply configure your web app to use your API. The `Syncano Client` library handles the rest. |
108 | | -4. When running `syncano-cli deploy chat`, you tell Syncano to read from the `socket.yml` spec and, based on it, build your own API endpoints. The endpoints are available for use instantly after the `deploy` command is finished. To keep your local changes in sync with the Instance during development you can use the `syncano-cli deploy --hot [socket-name]` command |
109 | | -5. `syncano-cli hosting add` is the last command. It publishes your static web assets from the `web` folder and hosts them on Syncano. |
| 42 | +Try to call endpoints using browser or any HTTP Client. |
110 | 43 |
|
111 | | -That's `it`! If you have any questions, log into our [Slack](https://syncano.io/#/slack-invite) and chat with the community. Happy coding! |
| 44 | +That's `it`! If you have any questions, join our [Spectrum community space](https://spectrum.chat/syncano). Happy coding! |
0 commit comments