Wodby 2 documentation improvements

2.0/docs/apps/builds.md

@@ -1,3 +1,26 @@
 # Application builds
 
+Some [services are buildable](../services/build.md), for such app services we expect a [CI system](../cicd/index.md) to build container images and trigger deployment via Wodby CLI. 
 
+## Build sources and buildable services
+
+1. There are app services that have a connected git repository from a git integration as a build source
+2. There are associated app services that also buildable but do not have a build source. We expect users to build images from both of these services during a build and triggering a deployment that provides build information for both of those services
+
+A simple example will be an app with Nginx and PHP services, where a git repository that contains both backend and frontend connected to a PHP service. During the build in addition to backend build (e.g. composer) user can build frontend code (e.g. nodejs) for Nginx. After building container images for the both services a user will run a release (`wodby ci release` to push to associated docker registry) and deployment (`wodby ci deploy`).
+
+## Build info
+
+A build always provides the following information:
+
+- Main app service with the build source (git repository) that provides the build pipeline
+- Build number
+- Associated stack revision
+- CI system that produced this build ([Wodby CI](../cicd/wodby-ci.md) by default)
+- Associated git repository
+- Related git commit information
+- Resulting docker images that should be deployed
+
+## Needs rebuild
+
+Similar to [`needs_redeploy`](deploys.md#needs-redeploy) app instance with buildable services will be marked as `needs rebuild` when buildable services changed. It is to indicate although there were changes they may not have yet applied, for example an environment variable value changed that may affect the build process. 

2.0/docs/apps/deploys.md

@@ -1,3 +1,21 @@
 # Application Deployments
 
+Deployments are selective and can be performed for specific services. During the first deployment all services deployed except buildable services. For buildable services the app instance's status set to `awaiting` until deployment with the build information triggered from [CI system](../cicd/index.md).
 
+A deployment always associated with a specific revision of app instance's stack's revision.
+
+## Build deployment
+
+Deployments from CI system can be triggered with `wodby ci deploy` command. For build deployment request a new deployment created associated with the build. Associated build can have multiple app service builds associated. Deployment from CI can optionally disable run of post-deployment scripts for the built services.
+
+## New deployment
+
+A new application deployment can be manually run from _Apps > [App] > Deploys > New Deployment_ page. Services to include to the deployment can optionally be run with the force flag, for such deployments a random hash will be added to the Kubernetes annotations to force actual resources deployment even if there are no changes in manifests. Post-deployments are enabled by default for services that provide them but can be disabled. For buildable service last successful build selected by default but can be chosen to older builds as long as the build's associated stack revision and the current app instance's stack revision are the same.
+
+## Needs redeploy
+
+When app service's configuration changed app instance's will be marked as `needs redeploy`. It is to indicate that although changes has been done to the app services they are not yet applied.
+
+!!! warning "Auto redeployment"
+
+    Please note that app instance can sometimes be redeployed automatically, for example when domains' certificates renewed the associated app services will be redeployed automatically when renewal succeeded. 

2.0/docs/apps/endpoints.md

@@ -8,9 +8,9 @@ Endpoints represent accessible endpoints to your app services. Endpoints consist
 
 By default, Wodby will generate technical domains for services in your application that have enabled HTTP routes. The technical domains built in the following way – `<service-name>.<instance-name>.<app-name>.<org-name>.wodby.app`. We will also automatically issue Let's Encrypt certificates for technical domains. Additionally, the main service with http routes will have a technical domain without a service name – `<instance-name>.<app-name>.<org-name>.wodby.app`.
 
-### TLS Certificates
+### SSL Certificates
 
-Wodby provides a simple way to issue a TLS (SSL) certificate for a domain in your endpoint. Currently, we support only [Let's Encrypt](https://letsencrypt.org/) issuer. We will automatically renew Let's Encrypt certificates before they expire. You can also review all certificates that we issued from your organization settings page. 
+Wodby provides a simple way to issue a SSL (TLS) certificate for a domain in your endpoint. Currently, we support only [Let's Encrypt](https://letsencrypt.org/) issuer. We will automatically renew Let's Encrypt certificates before they expire. You can also review all certificates that we issued from your organization settings page. 
 
 Custom certificates not currently supported.
 

2.0/docs/apps/env.md

@@ -1,3 +1,17 @@
 # Environment
 
+Environment is the category of application instance designed to separate production, development, testing and staging.  
 
+Environments can be created by a user in addition to default environments. 
+
+Environment has a type, at least one environment must per type.
+
+## Type
+
+The following environment types supported:
+
+- `dev`
+- `prod`
+- `staging`
+- `testing`
+- `feature`

2.0/docs/apps/tokens.md

@@ -4,11 +4,11 @@ Tokens are text values that can have a plain value or a regular expression that
 
 In an app tokens compiled and overridden from different levels:
 
-- Service defined tokens
-- Stack service define tokens
-- Stack-wide tokens
-- App instance tokens
-- App service tokens
+1. Service defined tokens
+2. Stack service define tokens
+3. Stack-wide tokens
+4. App instance tokens
+5. App service tokens
 
 In addition to custom user-defined Wodby provides the following tokens available depending on the context:
 

2.0/docs/integrations/index.md

@@ -1,55 +1,11 @@
 # Integrations
 
-Wodby provides native integration with third-party services through _providers_. _Integration_ represents a single connection between your Wodby account with your third-party service account. For example, you create a new integration of the AWS provider to connect your AWS account to Wodby to e.g. create a new EKS cluster.
+Wodby provides native integration with third-party services through [providers](providers.md). _Integration_ represents a single connection between your Wodby account with your third-party service account. For example, you create a new integration of the AWS provider to connect your AWS account to Wodby to e.g. create a new EKS cluster.
 
 ## Provider
 
 Apart from [variable](variable.md) type providers, all providers offered and maintained by Wodby. If you think there's a good provider that we should add to Wodby, please let us know. 
 
 ## Types
 
-Every provider can have multiple integration types it offers. When you create a new integration you can select which type you want to create. Supported integration types listed below:
-
-### Kubernetes
-
-- [Google Cloud Platform GKE](gcp.md#gke)
-- [Amazon Web Services EKS](aws.md#eks)
-- [Azure AKS](azure.md#aks)
-- [DigitalOcean DOKS](digitalocean.md#doks)
-- [OVH Kubernetes](ovh.md#kubernetes)
-- [Linode](linode.md#lke)
-
-### Databases
-
-- [Google Cloud Platform Cloud SQL](gcp.md#cloud-sql)
-- [Amazon Web Services RDS](aws.md#rds)
-- [Azure Databases](azure.md#databases)
-- [DigitalOcean Managed Database](digitalocean.md#managed-database)
-
-### Storage
-
-- [Amazon Web Services S3](aws.md#s3)
-- [Google Cloud Platform Cloud Storage](gcp.md#cloud-storage)
-- [Azure Blob Storage](azure.md#blob-storage)
-- [DigitalOcean Spaces](digitalocean.md#spaces)
-
-### CI/CD
-
-- [Wodby CI](../cicd/wodby-ci.md)
-- [CircleCI](circleci.md)
-- [GitHub Actions](github.md#actions)
-
-### Docker registry
-
-- [Wodby Registry](../cicd/wodby-registry.md)
-- [Docker Hub](docker.md)
-
-### Monitoring
-
-- [NewRelic](newrelic.md)
-- [Datadog](datadog.md)
-
-### Variable
-
-- [NewRelic](newrelic.md)
-- [Sentry](sentry.md)
+Every provider can have multiple [integration types](types.md) it offers. When you create a new integration you can select which type you want to create. 

2.0/docs/integrations/providers.md

@@ -0,0 +1,7 @@
+# Integration provider
+
+Provider is the representation of Wodby's integration with third-party services. One provider can have multiple [integration types](types.md) that can optionally be selected when a new integration created. 
+
+Except generic [variable integration](variable.md) all providers have a certain implementation logic depending on their type, for example for providers with kubernetes integration Wodby offers native-integration with the cloud services that provide managed Kubernetes solution.
+
+Only _variable_ providers can be created by users, all others provided by Wodby. If you miss a certain provider feel free to [contact us](../support.md) and suggest. 

2.0/docs/integrations/types.md

@@ -0,0 +1,62 @@
+# Integration types
+
+Every provider can have multiple integration types it offers. When you create a new integration you can select which type you want to create. Supported integration types listed below:
+
+## Git
+
+Machine name: `git`
+
+- [GitHub](github.md)
+- [GitLab](gitlab.md)
+- [BitBucket](bitbucket.md)
+
+## Kubernetes
+
+Machine name: `kubernetes`
+
+- [Google Cloud Platform GKE](gcp.md#gke)
+- [Amazon Web Services EKS](aws.md#eks)
+- [Azure AKS](azure.md#aks)
+- [DigitalOcean DOKS](digitalocean.md#doks)
+- [OVH Kubernetes](ovh.md#kubernetes)
+- [Linode](linode.md#lke)
+
+## Databases
+
+Machine name: `database`
+
+- [Google Cloud Platform Cloud SQL](gcp.md#cloud-sql)
+- [Amazon Web Services RDS](aws.md#rds)
+- [Azure Databases](azure.md#databases)
+- [DigitalOcean Managed Database](digitalocean.md#managed-database)
+
+## Storage
+
+Machine name: `storage`
+
+- [Amazon Web Services S3](aws.md#s3)
+- [Google Cloud Platform Cloud Storage](gcp.md#cloud-storage)
+- [Azure Blob Storage](azure.md#blob-storage)
+- [DigitalOcean Spaces](digitalocean.md#spaces)
+
+## CI/CD
+
+Machine name: `ci`
+
+- [Wodby CI](../cicd/wodby-ci.md)
+- [CircleCI](circleci.md)
+- [GitHub Actions](github.md#actions)
+
+## Docker registry
+
+Machine name: `docker-registry`
+
+- [Wodby Registry](../cicd/wodby-registry.md)
+- [Docker Hub](docker.md)
+
+## Variable
+
+Machine name: `variable`
+
+- [NewRelic](newrelic.md)
+- [Sentry](sentry.md)

2.0/docs/services/actions.md

@@ -1,3 +1,27 @@
 # Service actions
 
-Service can define an action that will execute an operation in an app. Such actions are accessible to run from Wodby Dashboard. Usually, it will be a kubernetes job that will run a copy of a main container with overridden `args` and/or `command` params.
+Service can define an action that will execute an operation in an app. When an action executed it will run a kubernetes job with the provided overridden args/commands and optionally privileged permissions. A task containing the logs of the execution will be created.
+
+Service with multiple actions will run all actions simultaneously unless there are action with dependency order specified.
+
+## Type
+
+Action's type defines how and when the action will be executed.
+
+### `button`
+
+Action's of this type will be shown as a button in Wodby dashboard. 
+
+### `post_deploy`
+
+Post-deployment action that will run after every service deployment. If deploy contains more than one service, the action will run only when all deployments succeeded. Can be limited to run only when a specific build source templates selected. 
+
+### `post_deploy_once`
+
+Same as `post_deploy` but run only during first deployment. Can be limited to run only when a specific build source templates selected.
+
+### `post_upgrade`
+
+Post-upgrade action
+
+

2.0/docs/services/annotations.md

@@ -0,0 +1,3 @@
+# Service annotations
+
+Service can provide annotations that will be added as Kubernetes annotations if associated Helm chart supports extra annotations. 

2.0/docs/services/backups.md

@@ -2,7 +2,12 @@
 
 Service can define data backups. There are two main methods of backups:
 
-1. Simple files backups from a path
-2. Action to create a backup, such as database backup
+## 1. Simple files backup
 
-In both cases, the resulting archive will be uploaded to a cloud storage bucket of a connected integration.
+We create a tarball with files from the specified directory. The tarball can optionally be gzipped.
+
+The tarball will be uploaded to a cloud storage bucket of a connected integration.
+
+## 2. Through action
+
+We run a kubernetes job with provided overridden args/command to create the backup archive. We expect to get an archive placed in the same volume as the result. The resulting archive will be uploaded to a cloud storage bucket of a connected integration.

2.0/docs/services/build.md

@@ -0,0 +1,16 @@
+# Service build
+
+Non-external services can be buildable. Such services will expect to receive a related build info during app deployment. 
+
+There are two main types of buildable services:
+
+1. Services that require a git repository connected
+2. Services that do not have a git repository but still expected to be built in [CI](../cicd/index.md) process
+
+## Build templates
+
+Services that require a git repository can also have build templates, those a public git repositories that contain a boilerplate and a pipeline. You can clone a build template repository under a selected [git integration](../integrations/index.md#git).
+
+## Dockerfile
+
+Services may specify a custom Dockerfile located in the same repository. This Dockerfile will be used during `wodby ci build [service]` command when [Wodby CI](../cicd/wodby-ci.md) used.

2.0/docs/services/cron.md

@@ -0,0 +1,3 @@
+# Cron schedules
+
+Service can define cron schedules to run. A schedule has a command/args to override for a kubernetes job to run and a schedule in crontab format. A schedule will run a cron job in accordance with the specified crontab. The cron job will have task associated that contains execution logs. 

2.0/docs/services/endpoints.md

@@ -0,0 +1,12 @@
+# Service endpoints
+
+Services that provide public ports can define endpoints. An endpoint is the collection of ports and domains. Services can define only ports in their manifests, domains can be added later after app creation.
+
+An endpoint designed to represent a single kubernetes service. 
+
+There are three type of ports:
+1. `http` - such ports allow domains with TLS certificates to be attached
+2. `udp` - such ports can be publicly exposed
+3. `tcp` - such ports can be publicly exposed
+
+One port per endpoint can be marked as main. When `http` port marked as main in the main endpoint, a main technical domain will be attached to it during app creation.

2.0/docs/services/imports.md

@@ -2,7 +2,12 @@
 
 Service can define data imports. There are two types of how imports performed:
 
-1. Simple files import from an archive
-2. A mount of an archive to a path known to a container, a container will perform the import on a start-up. Normally used for databases  
+## 1. Simple files import
 
-In #1 we run import directly in the running volume. In #2 we switch replace persistent volume to a new volume with new data only if the import via start-uip was successful.
+In this case we run import directly in the running volume by unpacking a provided tarball to a specified path. It's not transactional.
+
+## 2. Through init volume
+
+In this case we mount the import archive to the init volume provided by the service, a container will perform the import from the init volume during a start-up. Normally used for databases.
+
+This import is transactional. We spin up a copy of the app service with a new persistent volume, if the import successful we perform a service redeploy during which a new persistent volume with the imported files mounted.