mirror of
https://github.com/serverless/serverless.git
synced 2026-01-25 15:07:39 +00:00
Merge pull request #1381 from serverless/add-new-documentation-structure-for-alpha-1-release
Add new documentation structure for alpha 1 release
This commit is contained in:
Philipp Muens
GitHub
commit
0a5cab7236
@ -1,6 +1,6 @@
|
||||
|
||||
|
||||
Serverless Framework V.1 (BETA)
|
||||
Serverless Framework v.1.0
|
||||
=================================
|
||||
[](http://www.serverless.com)
|
||||
<!--- [](https://badge.fury.io/js/serverless) --->
|
||||
@ -19,7 +19,7 @@ Also, [we're hiring](mailto:jobs@serverless.com) :)
|
||||
|
||||
## Status
|
||||
|
||||
Serverless Framework V.1 is currently under construction and not yet ready.
|
||||
Serverless Framework v.1.0 is currently under construction and not yet ready.
|
||||
|
||||
## Features
|
||||
|
||||
|
||||
@ -17,62 +17,33 @@ service afterwards.
|
||||
4. `serverless invoke --function hello --stage dev --region us-east-1`
|
||||
5. `serverless remove --stage dev --region us-east-1`
|
||||
|
||||
## In depth
|
||||
## How to contribute to Serverless
|
||||
|
||||
- [Concepts](/docs/concepts)
|
||||
- [Services](/docs/concepts/services.md) - Understanding Serverless services
|
||||
- [serverless.yaml](/docs/concepts/serverless-yaml.md) - A look at the `serverless.yaml` file
|
||||
- [serverless.env.yaml](/docs/concepts/serverless-env-yaml.md) - A look at the `serverless.env.yaml` file
|
||||
- [Plugins](/docs/concepts/plugins.md) - How plugins work
|
||||
- [Guide](/docs/guide)
|
||||
- [Event sources](/docs/guide/event-sources.md) - Understand and use event sources
|
||||
- [Tutorials](/docs/tutorials)
|
||||
- [Your first service](/docs/tutorials/your-first-service.md) - Create, deploy, invoke and remove your first service
|
||||
- [Adding event sources](/docs/tutorials/adding-event-sources.md) - Learn how you can extend your services functionality
|
||||
with event sources
|
||||
- Plugins
|
||||
- [Core plugins](/lib/plugins)
|
||||
- [Create](/lib/plugins/create) - Creates a new Serverless service
|
||||
- [Deploy](/lib/plugins/deploy) - Deploy your resources to your provider
|
||||
- [Invoke](/lib/plugins/invoke) - Invoke your function
|
||||
- [Remove](/lib/plugins/remove) - Remove a deployed service
|
||||
- [AWS plugins](/lib/plugins/aws)
|
||||
- [Compile Functions](/lib/plugins/aws/deploy/compile/functions) - Compiles functions to
|
||||
CloudFormation resources
|
||||
- [Compile S3 Events](/lib/plugins/aws/deploy/compile/events/s3) - Compiles S3 events to
|
||||
CloudFormation resources
|
||||
- [Compile Scheduled Events](/lib/plugins/aws/deploy/compile/events/schedule) - Compiles scheduled
|
||||
events to CloudFormation resources
|
||||
- [Compile Api Gateway Events](/lib/plugins/aws/deploy/compile/apiGateway) - Compiles http events
|
||||
to CloudFormation resources
|
||||
- [Deploy](/lib/plugins/aws/deploy) - Deploys the service to AWS
|
||||
- [Invoke](/lib/plugins/aws/invoke) - Invokes an AWS lambda function
|
||||
- [Remove](/lib/plugins/aws/remove) - Removes the service with all it's resources from AWS
|
||||
We love our community! Contributions are always welcomed!
|
||||
Jump right into our [issues](https://github.com/serverless/serverless/issues) to join existing discussions or open up
|
||||
new ones if you have a bug or want to improve Serverless.
|
||||
|
||||
## FAQ
|
||||
Also feel free to open up [pull request](https://github.com/serverless/serverless/pulls) which resolves issues!
|
||||
|
||||
> Where do I start when I want to write apps with Serverless?
|
||||
You may also take a look at our [contributing guidelines](/CONTRIBUTING.md).
|
||||
|
||||
You should take a look at the [tutorials](/docs/tutorials) where you will find different guides which will help you
|
||||
with your first application (there's also a ["Your first service"](/docs/tutorials/your-first-service.md) tutorial).
|
||||
## User documentation
|
||||
|
||||
> I want to integrate provider X. How does this work?
|
||||
|
||||
You can implement your provider of choice with he help of plugins. Start by reading the [plugin concept](/docs/concepts/plugins.md)
|
||||
to get an overview how plugins work. After that you might want to take a look at the [AWS Deploy](/lib/plugins/aws/deploy)
|
||||
plugin which will explain to you how the AWS provider is implemented / works.
|
||||
|
||||
We'd recommend to take a look at the different sources of the [plugins](/lib/plugins) as they show implementation
|
||||
details and best practices which will help you integrate your provider easily.
|
||||
|
||||
> How does Serverless work?
|
||||
|
||||
The [concepts](/docs/concepts) folder in the docs will help you understand how Serverless works.
|
||||
|
||||
> I found a bug / encountered a strange error
|
||||
|
||||
Please take a look at our [issues](https://github.com/serverless/serverless/issues) to see if someone else has faced
|
||||
the same problem.
|
||||
|
||||
Contributions are always welcomed! Just open up a new issue to start the discussion or submit a pull request
|
||||
which fixes the bug.
|
||||
- [Understanding Serverless and its configuration files](understanding-serverless)
|
||||
- [Serverless services and functions](understanding-serverless/services-and-functions.md)
|
||||
- [serverless.yaml](understanding-serverless/serverless-yaml.md)
|
||||
- [serverless.env.yaml](understanding-serverless/serverless-env-yaml.md)
|
||||
- [How to build your Serverless services](guide)
|
||||
- [Installing Serverless](guide/installation.md)
|
||||
- [Creating a service](guide/creating-a-service.md)
|
||||
- [Deploying your service](guide/deploying-a-service.md)
|
||||
- [Invoking your functions](guide/invoking-a-function.md)
|
||||
- [Adding additional event sources](guide/event-sources.md)
|
||||
- [Managing custom provider resources](guide/custom-provider-resources.md)
|
||||
- [Removing your service](guide/removing-a-service.md)
|
||||
- [Using plugins](using-plugins)
|
||||
- [How to use additional plugins in your service](using-plugins/adding-custom-plugins.md)
|
||||
- [Plugins provided by Serverless](using-plugins/core-plugins.md)
|
||||
- [Building plugins](developing-plugins)
|
||||
- [How to build your own plugin](developing-plugins/building-plugins.md)
|
||||
- [How to build provider integration with your plugin](developing-plugins/building-provider-integrations.md)
|
||||
|
||||
@ -1,3 +0,0 @@
|
||||
# Concepts
|
||||
|
||||
The "concepts" section provides documents for a deep dive into the different concepts Serverless is built upon.
|
||||
10
docs/developing-plugins/README.md
Normal file
10
docs/developing-plugins/README.md
Normal file
@ -0,0 +1,10 @@
|
||||
# Developing plugins
|
||||
|
||||
Here you can read how to develop your own Serverless plugins. We'll get into details on how to write custom plugins to
|
||||
extend the functionality of Serverless. Furthermore we'll look into the way how you can use your plugin knowledge
|
||||
to integrate your own provider into the Serverless framework.
|
||||
|
||||
## Table of contents
|
||||
|
||||
- [Building plugins](building-plugins.md)
|
||||
- [Building provider integrations](building-provider-integrations.md)
|
||||
@ -1,4 +1,4 @@
|
||||
# Plugin System and Lifecycle Management
|
||||
# Building plugins
|
||||
|
||||
The Serverless Plugin System is at the core of our Framework. It supports any feature we build, it decides how fast we
|
||||
can build them, how easily testable they are and how approachable they are for our users.
|
||||
@ -251,8 +251,8 @@ A user has to define the plugins they want to use in the root level of the serve
|
||||
|
||||
```yaml
|
||||
plugins:
|
||||
- custom_plugin_1
|
||||
- custom_plugin_2
|
||||
- custom_plugin_1
|
||||
- custom_plugin_2
|
||||
```
|
||||
|
||||
We do not auto-detect plugins from installed dependencies so users do not run into any surprises and we cut down on the
|
||||
@ -295,11 +295,10 @@ E.g. we defined the following event for a function:
|
||||
|
||||
```yaml
|
||||
events:
|
||||
aws:
|
||||
S3: bucket_name
|
||||
- s3: bucket_name
|
||||
```
|
||||
|
||||
The SimpleS3Event plugin could now bind to the configureEvent Lifecycle Event, read this configuration and add
|
||||
The S3 event plugin could now bind to the configureEvent Lifecycle Event, read this configuration and add
|
||||
appropriate resources to the CloudFormation configuration. Then once the AWSResourceDeployment plugin converts the
|
||||
CloudFormation syntax we’ve stored in the object into an actual CloudFormation stack file it will include all of the
|
||||
configuration necessary to create the Bucket and set it up to trigger the Lambda function we’re also deploying.
|
||||
@ -0,0 +1 @@
|
||||
# Building provider integrations
|
||||
@ -1,4 +1,19 @@
|
||||
# Guide
|
||||
|
||||
This guide will help you build your Serverless services. Furthermore it will provide best practices and patterns you can
|
||||
use while developing your Serverless application.
|
||||
This guide will help you building your Serverless services.
|
||||
We'll start by givin you information on how to install Serverless. After that we create and deploy a service, invoke a
|
||||
services function and add additional event sources to our function.
|
||||
|
||||
At the end we'll add custom provider resources to our service and remove it.
|
||||
|
||||
This guide is Amazon web service specific but can be applied to any other provider as the steps are similar.
|
||||
|
||||
## Table of contents
|
||||
|
||||
- [Installation](installation.md)
|
||||
- [Creating a service](creating-a-service.md)
|
||||
- [Deploying a service](deploying-a-service.md)
|
||||
- [Invoking a function](invoking-a-function.md)
|
||||
- [Event sources](event-sources.md)
|
||||
- [Custom provider resources](custom-provider-resources.md)
|
||||
- [Removing a service](removing-a-service.md)
|
||||
|
||||
14
docs/guide/creating-a-service.md
Normal file
14
docs/guide/creating-a-service.md
Normal file
@ -0,0 +1,14 @@
|
||||
# Creating a service
|
||||
|
||||
`cd` into a directory of your choice and run `serverless create --name my-service --provider aws`.
|
||||
Serverless will create a skeleton for your new Serverless service inside the `my-service` directory.
|
||||
|
||||
Type `cd my-service` to navigate into the previously created directory.
|
||||
|
||||
## Open the service inside an editor
|
||||
|
||||
Open the directory with your favorite editor. You should see some files. One of those is the `serverless.yaml` file.
|
||||
This file holds all the important information about your service. You should see e.g. a `functions` definition where
|
||||
one function is defined.
|
||||
|
||||
You don't have to understand what's going on here as we'll go into more details about this file in upcoming tutorials.
|
||||
1
docs/guide/custom-provider-resources.md
Normal file
1
docs/guide/custom-provider-resources.md
Normal file
@ -0,0 +1 @@
|
||||
# Custom provider resources
|
||||
4
docs/guide/deploying-a-service.md
Normal file
4
docs/guide/deploying-a-service.md
Normal file
@ -0,0 +1,4 @@
|
||||
# Deploying a service
|
||||
|
||||
Let's deploy our service by typing `serverless deploy`. You should see a prompt which informs you once the corresponding
|
||||
resources are deployed to AWS.
|
||||
@ -1,5 +1,69 @@
|
||||
# Event sources
|
||||
|
||||
Serverless is used to build event driven architecture. Basically everything a function can trigger is an event.
|
||||
Events could be HTTP requests, events fired from a cloud storage, scheduled events, etc.
|
||||
|
||||
This tutorial will show you how you can add event sources to your Serverless service.
|
||||
|
||||
We'll assume that you have Serverless v1.0 or greater installed on your machine.
|
||||
|
||||
Our provider we use throughout the tutorial will be Amazon web services (AWS).
|
||||
|
||||
**Note:** This tutorial will implement a schedule event for a function which is deployed to Amazon web services.
|
||||
You can re-use this tutorial to add [other event sources](/docs/guide/event-sources.md)
|
||||
(even from other providers) to your functions.
|
||||
|
||||
## Scheduling a function
|
||||
|
||||
Let's pretend we want to re-run our function every 10 minutes. One solution would be to open up the cloud provider dashboard
|
||||
and run the function by hand but this is of course not the best way to solve our problem.
|
||||
|
||||
You might be familiar with so called "Cron jobs" if you're a UNIX user. Cron jobs are a way to define reoccurring
|
||||
tasks the operating system will trigger automatically (e.g. some sort of scripts that automates something for you).
|
||||
|
||||
AWS has introduced a similar way we can automate the way our lambda function get's called.
|
||||
|
||||
## Adding the schedule event source
|
||||
|
||||
Let's add a schedule event source to a function in our Serverless service.
|
||||
|
||||
Go to the Serverless service directory and open up the `serverless.yaml` file. Navigate to the function of your choice
|
||||
where you want to add an event source. Add a new entry `events` inside the function. It should be on the same level as
|
||||
the `handler` entry.
|
||||
|
||||
After that add a `- schedule: rate(10 minutes)` entry inside the `events` definition.
|
||||
|
||||
Not the content of your `serverless.yaml` file might look like this:
|
||||
|
||||
```yaml
|
||||
functions:
|
||||
greet:
|
||||
handler: handler.greet
|
||||
events:
|
||||
- schedule: rate(10 minutes)
|
||||
```
|
||||
|
||||
That's it for the event addition. Next up we need to (re)deploy our service to enable our scheduled event.
|
||||
|
||||
## (Re)deploying the Serverless service
|
||||
|
||||
Run `serverless deploy` to (re)deploy the whole service.
|
||||
Your function will be scheduled to run every 10 minutes once the deployment has finished.
|
||||
|
||||
## Conclusion
|
||||
|
||||
Event sources are a great way to extend the functionality of your functions.
|
||||
They are pretty easy to setup. You simply need to add them to the corresponding function in your services `serverless.yaml`
|
||||
file and (re)deploy the service.
|
||||
|
||||
Serverless has implementations for different provider independent and provider specific event sources you can use.
|
||||
|
||||
Curious what events are available? Here's a list with [all available events](/docs/guide/event-sources.md).
|
||||
|
||||
---
|
||||
|
||||
# Event sources
|
||||
|
||||
With Serverless you write event driven architectures. An event can be e.g. a HTTP request, a schedule event or even
|
||||
an event when someone uploads a file to a cloud storage.
|
||||
|
||||
|
||||
1
docs/guide/installation.md
Normal file
1
docs/guide/installation.md
Normal file
@ -0,0 +1 @@
|
||||
# Installation
|
||||
10
docs/guide/invoking-a-function.md
Normal file
10
docs/guide/invoking-a-function.md
Normal file
@ -0,0 +1,10 @@
|
||||
# Invoking a function
|
||||
|
||||
Next up we'll invoke the `hello` function from our service (this example function was automatically created when we
|
||||
initially created our service).
|
||||
|
||||
Run `serverless invoke --function hello --stage dev --region us-east-1` to tell Serverless that you want to run the function.
|
||||
|
||||
The function get's invoked and you should see a message on your console.
|
||||
|
||||
Great! We've just executed our first function from our Serverless service!
|
||||
6
docs/guide/removing-a-service.md
Normal file
6
docs/guide/removing-a-service.md
Normal file
@ -0,0 +1,6 @@
|
||||
# Removing a service
|
||||
|
||||
Let's remove our service entirely from our provider. This is pretty easy. Just run `serverless remove --stage dev
|
||||
--region us-east-1` to remove everything.
|
||||
|
||||
A prompt will inform you once everything is removed.
|
||||
@ -1,4 +0,0 @@
|
||||
# Tutorials
|
||||
|
||||
This section provides different tutorials you can follow to build example services and explore what Serverless can be
|
||||
used for and is capable of.
|
||||
@ -1,61 +0,0 @@
|
||||
# Adding event sources
|
||||
|
||||
Serverless is used to build event driven architecture. Basically everything a function can trigger is an event.
|
||||
Events could be HTTP requests, events fired from a cloud storage, scheduled events, etc.
|
||||
|
||||
This tutorial will show you how you can add event sources to your Serverless service.
|
||||
|
||||
We'll assume that you have Serverless v1.0 or greater installed on your machine.
|
||||
|
||||
Our provider we use throughout the tutorial will be Amazon web services (AWS).
|
||||
|
||||
**Note:** This tutorial will implement a schedule event for a function which is deployed to Amazon web services.
|
||||
You can re-use this tutorial to add [other event sources](/docs/guide/event-sources.md)
|
||||
(even from other providers) to your functions.
|
||||
|
||||
## Scheduling a function
|
||||
|
||||
Let's pretend we want to re-run our function every 10 minutes. One solution would be to open up the cloud provider dashboard
|
||||
and run the function by hand but this is of course not the best way to solve our problem.
|
||||
|
||||
You might be familiar with so called "Cron jobs" if you're a UNIX user. Cron jobs are a way to define reoccurring
|
||||
tasks the operating system will trigger automatically (e.g. some sort of scripts that automates something for you).
|
||||
|
||||
AWS has introduced a similar way we can automate the way our lambda function get's called.
|
||||
|
||||
## Adding the schedule event source
|
||||
|
||||
Let's add a schedule event source to a function in our Serverless service.
|
||||
|
||||
Go to the Serverless service directory and open up the `serverless.yaml` file. Navigate to the function of your choice
|
||||
where you want to add an event source. Add a new entry `events` inside the function. It should be on the same level as
|
||||
the `handler` entry.
|
||||
|
||||
After that add a `- schedule: rate(10 minutes)` entry inside the `events` definition.
|
||||
|
||||
Not the content of your `serverless.yaml` file might look like this:
|
||||
|
||||
```yaml
|
||||
functions:
|
||||
greet:
|
||||
handler: handler.greet
|
||||
events:
|
||||
- schedule: rate(10 minutes)
|
||||
```
|
||||
|
||||
That's it for the event addition. Next up we need to (re)deploy our service to enable our scheduled event.
|
||||
|
||||
## (Re)deploying the Serverless service
|
||||
|
||||
Run `serverless deploy` to (re)deploy the whole service.
|
||||
Your function will be scheduled to run every 10 minutes once the deployment has finished.
|
||||
|
||||
## Conclusion
|
||||
|
||||
Event sources are a great way to extend the functionality of your functions.
|
||||
They are pretty easy to setup. You simply need to add them to the corresponding function in your services `serverless.yaml`
|
||||
file and (re)deploy the service.
|
||||
|
||||
Serverless has implementations for different provider independent and provider specific event sources you can use.
|
||||
|
||||
Curious what events are available? Here's a list with [all available events](/docs/guide/event-sources.md).
|
||||
@ -1,54 +0,0 @@
|
||||
# Your first service
|
||||
|
||||
In this tutorial we'll create and use our very first Serverless service.
|
||||
We'll create a new service, deploy it, invoke the first function and remove the whole service afterwards.
|
||||
|
||||
Our provider we use throughout the tutorial will be Amazon web services (AWS).
|
||||
|
||||
We'll assume that you have Serverless v1.0 or greater installed on your machine.
|
||||
|
||||
Excited? Let's go.
|
||||
|
||||
## Creating a new service
|
||||
|
||||
`cd` into a directory of your choice and run `serverless create --name my-service --provider aws`.
|
||||
Serverless will create a skeleton for your new Serverless service inside the `my-service` directory.
|
||||
|
||||
Type `cd my-service` to navigate into the previously created directory.
|
||||
|
||||
## Open the service inside an editor
|
||||
|
||||
Open the directory with your favorite editor. You should see some files. One of those is the `serverless.yaml` file.
|
||||
This file holds all the important information about your service. You should see e.g. a `functions` definition where
|
||||
one function is defined.
|
||||
|
||||
You don't have to understand what's going on here as we'll go into more details about this file in upcoming tutorials.
|
||||
|
||||
## Deploying the service
|
||||
|
||||
Let's deploy our service by typing `serverless deploy`. You should see a prompt which informs you once the corresponding
|
||||
resources are deployed to AWS.
|
||||
|
||||
## Invoking your function
|
||||
|
||||
Next up we'll invoke the `hello` function from our service (this example function was automatically created when we
|
||||
initially created our service).
|
||||
|
||||
Run `serverless invoke --function hello --stage dev --region us-east-1` to tell Serverless that you want to run the function.
|
||||
|
||||
The function get's invoked and you should see a message on your console.
|
||||
|
||||
Great! We've just executed our first function from our Serverless service!
|
||||
|
||||
## Removing the service
|
||||
|
||||
Let's remove our service entirely from our provider. This is pretty easy. Just run `serverless remove --stage dev
|
||||
--region us-east-1` to remove everything.
|
||||
|
||||
A prompt will inform you once everything is removed.
|
||||
|
||||
## Conclusion
|
||||
|
||||
Congratulations, you've just created, deployed, invoked and removed your very first Serverless service!
|
||||
|
||||
You're interested to learn more about Serverless? Visit the [tutorials section](/docs/tutorials) to see other tutorials!
|
||||
13
docs/understanding-serverless/README.md
Normal file
13
docs/understanding-serverless/README.md
Normal file
@ -0,0 +1,13 @@
|
||||
# Understanding Serverless
|
||||
|
||||
Here we'll take a deep dive into the internals of Serverless and understand what a service is and how functions relate
|
||||
to a service.
|
||||
|
||||
Additionally we look at the Serverless key pieces of each service which are the `serverless.yaml` and
|
||||
`serverless.env.yaml` files.
|
||||
|
||||
## Table of contents
|
||||
|
||||
- [Serverless services and functions](services-and-functions.md)
|
||||
- [serverless.yaml](serverless-yaml.md)
|
||||
- [serverless.env.yaml](serverless-env-yaml.md)
|
||||
9
docs/using-plugins/README.md
Normal file
9
docs/using-plugins/README.md
Normal file
@ -0,0 +1,9 @@
|
||||
# Using plugins
|
||||
|
||||
Learn how you can use plugins to extend Serverless functionality.
|
||||
Furthermore see a list of core plugins Serverless provides.
|
||||
|
||||
## Table of contents
|
||||
|
||||
- [Adding custom plugins](adding-custom-plugins.md)
|
||||
- [Core plugins](core-plugins.md)
|
||||
1
docs/using-plugins/adding-custom-plugins.md
Normal file
1
docs/using-plugins/adding-custom-plugins.md
Normal file
@ -0,0 +1 @@
|
||||
# Adding custom plugins
|
||||
18
docs/using-plugins/core-plugins.md
Normal file
18
docs/using-plugins/core-plugins.md
Normal file
@ -0,0 +1,18 @@
|
||||
# Core plugins
|
||||
|
||||
This is a list of all plugins which ship with Serverless. Click on each plugin to read what it does, how it works and
|
||||
see the corresponding source code.
|
||||
|
||||
- Core plugins
|
||||
- [Create](/lib/plugins/create)
|
||||
- [Deploy](/lib/plugins/deploy)
|
||||
- [Invoke](/lib/plugins/invoke)
|
||||
- [Remove](/lib/plugins/remove)
|
||||
- Amazon Web Services
|
||||
- [Compile Functions](/lib/plugins/aws/deploy/compile/functions)
|
||||
- [Compile S3 Events](/lib/plugins/aws/deploy/compile/events/s3)
|
||||
- [Compile Scheduled Events](/lib/plugins/aws/deploy/compile/events/schedule)
|
||||
- [Compile Api Gateway Events](/lib/plugins/aws/deploy/compile/apiGateway)
|
||||
- [Deploy](/lib/plugins/aws/deploy)
|
||||
- [Invoke](/lib/plugins/aws/invoke)
|
||||
- [Remove](/lib/plugins/aws/remove)
|
||||
Loading…
x
Reference in New Issue
Block a user