Skip to content
This repository was archived by the owner on May 20, 2025. It is now read-only.

Introduction, Installation, and Quickstart #628

Merged
merged 3 commits into from
Oct 10, 2024
Merged

Introduction, Installation, and Quickstart #628

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
f830091
update introduction page
HomelessDinosaur Oct 10, 2024
9309a00
update installation page
HomelessDinosaur Oct 10, 2024
53ca0bd
update links and quickstart
HomelessDinosaur Oct 10, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
10 changes: 5 additions & 5 deletions docs/get-started/installation.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,7 @@ description: 'Basic installation instructions for the Nitric Framework'

## Prerequisites

Nitric relies on functionality from the following projects to help retrieve plugins, containerize and deploy your application.
Nitric relies on functionality from the following projects to help retrieve plugins, containerize, and deploy your application.
Please follow these links to the official installation steps for each.

- [Git](https://git-scm.com/)
Expand All @@ -15,9 +15,9 @@ Please follow these links to the official installation steps for each.
- [Pulumi](https://www.pulumi.com/docs/cli/) _(for deployments, only needed if using the default providers)_

<Note>
When setting up docker on Linux be sure to follow the [post-installation
When setting up Docker on Linux be sure to follow the [post-installation
steps](https://docs.docker.com/engine/install/linux-postinstall/) so you can
run docker as a non-root user.
run Docker as a non-root user.
</Note>

## Installing the Nitric CLI
Expand Down Expand Up @@ -93,5 +93,5 @@ You can view the CLI release notes on our [CLI GitHub Releases page](https://git

## What's next

- Start building with the [quick start guide](./get-started/quickstart).
- Checkout out the [foundations](/foundations/why-nitric) section for a more detailed introduction to Nitric.
- Start building with the [quick start guide](/get-started/quickstart).
- Checkout out the [foundations](/get-started/foundations/why-nitric) section for a more detailed introduction to Nitric.
67 changes: 23 additions & 44 deletions docs/get-started/quickstart.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -37,7 +37,7 @@ curl -L "https://nitric.io/install?version=latest" | bash

<Note>
For more installation options and dependency information review the full
[installation guide](/getting-started/installation).
[installation guide](/get-started/installation).
</Note>

## Using the `new` command
Expand Down Expand Up @@ -118,8 +118,8 @@ npm install
cd hello-world

# We recommend using [Pipenv](https://pipenv.pypa.io/en/latest/) for dependency and virtual environments
# We have included it in our python templates.
# Installation instructions: https://pipenv.pypa.io/en/latest/installation/#preferred-installation-of-pipenv
# We have included it in our python templates.
# Installation instructions: https://pipenv.pypa.io/en/latest/installation/#preferred-installation-of-pipenv
pipenv install --dev
```

Expand Down Expand Up @@ -226,55 +226,35 @@ Your project should now look like this:

## Running your app

Nitric provides a local development server offering emulated versions of cloud services, suitable for local development/testing. You can use the Nitric CLI to start the local server using the `nitric start` command.
Nitric provides a local development environment offering emulated versions of cloud services, suitable for local development/testing. You can use the Nitric CLI to start your application and the local environment using the `nitric start` command.

```bash
nitric start
```

Nitric will automatically run your application using the service start script, this is located in your `nitric.yaml`.

After your service is running, it will register itself with the server. All the APIs are locally hosted on their own port, which will be displayed in the CLI output as `http://localhost:<port_number>`.
```yaml title:nitric.yaml
name: example
services:
- match: services/*.ts
start: npm run dev:services $SERVICE_PATH
```

All the APIs are locally hosted on their own port, which will be displayed in the CLI output as `http://localhost:<port_number>`.

The output will also show the local dashboard URL, the dashboard will automatically refresh with API details and other useful tools for building your application.
The output will also show the [local dashboard](/get-started/foundations/projects/local-development#local-dashboard) URL, the dashboard will automatically refresh with details about your resources and tools to interact with each of them.

Once the API is registered, you can test the API using any HTTP client, your browser, or the [local dashboard](/getting-started/local-dashboard):
Once the API is registered, you can test the API using any HTTP client, your browser, or the [local dashboard](/get-started/foundations/projects/local-development#local-dashboard):

```bash
curl http://localhost:4001/hello/John
Hello John
```

## Your local dashboard

Access the [local development dashboard](./local-dashboard) by opening the URL and port displayed in the CLI output.

The development dashboard is a powerful tool designed to help you move faster when developing new features. With the API explorer, you can easily access automatically generated endpoints and path params. Additionally, the Schedules Explorer allows you to trigger your schedules with ease, making it easier than ever to stay on top of your tasks. Make the most of your local development process with this essential tool.

Watch this brief video to see the development dashboard in action. You'll get a firsthand look at how the dashboard streamlines your development process by showcasing the [debugging](/guides/nodejs/debugging) of APIs and schedules in the popular code editor, VS Code.

<div>
<div className="video-container">
<iframe
src="https://www.youtube-nocookie.com/embed/cjbg-klgDNM"
title="YouTube video player"
frameBorder="0"
allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share"
allowFullScreen
/>
</div>
</div>

<Note>
The video currently showcases v0 of the local dashboard and will be updated
soon.
</Note>

## Making updates

Nitric's language templates enable hot-reloading by default, so at this point, you can start making changes to services and see what happens.

Start by opening the `hello` service in your editor and adding a new route to the API, then save, and execute the file:
At this point, you can start making changes to services. Start by opening the `hello` service in your editor and adding a new route to the API:

<CodeSwitcher tabs>

Expand Down Expand Up @@ -397,31 +377,31 @@ void main() {

<Note>
Depending on the language you choose the template may support hot-reloading,
if not you'll need to restart the service.
if not you'll need to restart the `nitric start` command.
</Note>

After saving the file, the new route will be registered and you can test it:
After making the change, the new route will be registered and you can test it:

```bash
curl http://localhost:4001/goodbye/John
Goodbye John
```

When you're finished testing, you can stop your application and the Nitric Server.
When you're finished testing, you can stop the application.

## Deploying the app

Now that you've implemented a basic API and tested that it works, you can deploy it to one or more cloud platforms. Applications built with Nitric can be automatically deployed and run on multiple cloud providers without any code changes.

The first step is to set up your credentials for the cloud provider.

- [AWS](/reference/providers/aws)
- [Azure](/reference/providers/azure)
- [GCP](/reference/providers/gcp)
- [AWS](/providers/pulumi/aws)
- [Azure](/providers/pulumi/azure)
- [GCP](/providers/pulumi/gcp)

You'll then need to create a [stack](/reference/cli#stacks) that represents your project and a deployment target.
You'll then need to create a [stack](/get-started/foundations/deployment#stacks) that represents your project and a deployment target.

The `stack new` command below will create a stack named `dev` that uses the `aws` provider.
The `nitric stack new` command below will create a stack named `dev` that uses the `aws` provider.

```bash
nitric stack new dev aws
Expand All @@ -446,5 +426,4 @@ nitric down
# What's next?

- Learn more about [APIs](/apis)
- See other features in the [introduction](/#building-blocks)
- Learn more about the [foundations](/foundations/projects) of Nitric
62 changes: 20 additions & 42 deletions docs/index.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -97,7 +97,7 @@ void main() {

</div>

If you're familiar Nitric already, you might want to jump to the [Installation](/getting-started/installation), [Guides](/guides) or [Resources](/apis) sections. Otherwise, keep reading to learn more about Nitric.
If you're familiar Nitric already, you might want to jump to the [Installation](/get-started/installation), [Guides](/guides) or [Resources](/apis) sections. Otherwise, keep reading to learn more about Nitric.

---

Expand All @@ -112,7 +112,7 @@ services:
start: npm run dev:services $SERVICE_PATH
```

You might have one service that handles everything, or a service for each route. It's up to you. Every matched service becomes a container, allowing them run and scale independently.
You might have one service that handles everything, or a service for each route. It's up to you. Every matched service becomes a container, allowing them to run and scale independently.

---

Expand Down Expand Up @@ -153,9 +153,7 @@ import (
func main() {
profiles, _ := nitric.NewBucket("profiles").Allow(nitric.BucketRead, nitric.BucketWrite, nitric.BucketDelete)

if err := nitric.Run(); err != nil {
fmt.Println(err)
}
nitric.Run()
}
```

Expand Down Expand Up @@ -369,7 +367,7 @@ curl -L "https://nitric.io/install?version=latest" | bash

<Note>
Nitric has a few dependencies, like Docker, which you can read about in the
[Installation](/getting-started/installation) section.
[Installation](/get-started/installation) section.
</Note>

### New
Expand All @@ -389,8 +387,9 @@ nitric start
```

<Note>
Start also emulates the resources you requested, so you can test your app
locally. And provides a Dashboard UI to interact with the resources.
Start also emulates the resources you requested, so you can [test your app
locally](/get-started/foundations/projects/local-development). And provides a
Dashboard UI to interact with the resources.
</Note>

### Deploy
Expand Down Expand Up @@ -512,47 +511,26 @@ print(response.contents);

</CodeSwitcher>

### Manual Install
### Overriding

Alternatively, you can download pre-compiled binaries from the [releases](https://github.com/nitrictech/cli/releases) page and install them manually.
If you need to change how Nitric deploys a resources or how it interacts with a service at runtime, you can [extend or modify a provider](/providers/custom/extend).

## Update to the latest version

<InstallNitricTabs>

<TabItem label="macOS">

```bash
brew upgrade nitric
```

</TabItem>

<TabItem label="Windows">

```bash
scoop update nitric
```

</TabItem>

<TabItem label="Linux">

```bash
curl -L "https://nitric.io/install?version=latest" | bash
```
<Note>
For example, here's a [project that swaps SNS for
EventBridge](https://github.com/jyecusch/iac-ifc-comparison) on AWS.
</Note>

</TabItem>
### Full Customization

</InstallNitricTabs>
If you need to deploy to a new platform or new set of services that Nitric doesn't support, you can [build your own provider](/providers/custom/create). This is a bit more advanced, but it's the ultimate escape hatch.

You can easily check which version you're on by running `nitric version`.
The included providers are written in Go and built using Terraform or Pulumi, but you can use any language or tool you like.

## Release notes
### Additional Resources

You can view the CLI release notes on our [CLI GitHub Releases page](https://github.com/nitrictech/cli/releases).
If you need to use a service/resource that Nitric doesn't support, you do that like you always would. Nitric doesn't get in the way of you using the cloud, it just makes it easier.

## What's next

- Start building with the [quick start guide](./get-started/quickstart).
- Checkout out the [foundations](/foundations/why-nitric) section for a more detailed introduction to Nitric.
- Start building with the [quick start guide](/get-started/quickstart).
- Checkout out the [foundations](/get-started/foundations/why-nitric) section for a more detailed introduction to Nitric.
Loading