Welcome!

We are happy that you're here! 👋

So what is code.store? It all started with a simple idea: the complexity of the modern world is astonishing and is increasing every day, that's why we should be spending our time and energy on problems that are new and complex to solve and try and reuse everything else. So we decided to create a platform for companies and software engineers to reuse and share live, hosted code among projects and organizations. We also want to create a public marketplace where every developer and company could sell their API-first services on a subscription or pay-per-call rate-plan.

So, in short, code.store is a backend-as-a-service, a GraphQL schema-first platform where you can build, host, reuse, and bill your so that you could create some truly amazing products!

For the good of your company and the planet, we think that reusing code is very important!

Community

Like many other great products, code.store is continuously evolving as we are striving to bring more features, improve the existing ones and make sure that the product is as stable as it could be. 🤞

That's why if you have ANY suggestions while using code.store, whether it be feature requests, suggestions on how to improve our documentation, or just some questions, we are here for you!

Create a feature request or chat with us in real-time in our community home here: .

What next?

A good to place to start would be to read about , and of course, our .

Enjoy the reading and don't hesitate to !

♻️ Reusability

We created code.store because we believe the way software is being built today is not adapted to the pace of the modern world. We think that you should not spend time on problems that have been already solved in the past.

Software started with fully custom-built monoliths. Large mono-repository projects where teams coded absolutely everything. Then came frameworks and software editor solutions (Magento, Drupal, Wordpress, Salesforce, SAP...), providing vertical monoliths for common needs (CRM, e-commerce, ERP, DAM, PIM, ...). Usually, clients of software editor solutions end up overpaying for features they don't use (a client uses only 30% of features on average), and they still have an ever-growing budget for maintenance of a massive monolith.

Now is the time to build software in a new way: re-using small building blocks that solve a unique functional problem, like using lego bricks.

‌Modules, packages, DLLs, JARs, servlets, there has always been a desire for reusability, but there were always many barriers to reusability: technological stack, support & maintenance, integration, compatibility, and size of each component, the coupling between UX and back-end.

So why it would be different with code.store?

In the past years, the world of web-development saw several profound changes in the way we build software that makes out code.store idea reasonable:

• Headless and decoupled approaches

  With robust and stable frontend frameworks like Angular, React, and Vue, it is now easy to build genuinely decoupled applications. It is important because the strongest barrier to reusability is frontend and UX. With decoupling, we can focus on API reusability.

• GraphQL

  It offers a lot of flexibility to frontend developers. Previously, each time an application needed a product listing presented in a slightly different way, we would either have to load all the unnecessary data from a single REST endpoint or ask backend developers to provide a new "lighter" endpoint.

💰Revenues

When independent developers, companies, or digital agencies build software for others, they usually bill the time they spent on it. It's therefore complicated to re-use components from one project to another, and almost impossible to share funding, specifically when you mix hosting and support. We wanted to change that paradigm by providing a new way for billing projects.

For each service on code.store, you may activate metered or monthly billing and sell them to your clients. We take care of retrieving funds and take a small cut of only 10%. The recurring revenues cover your initial development time, hosting resources, our platform, and the time you spent on the support and maintenance of your service.

Nowadays, « Every company is a tech company », but being a software editor is not easy. Initial technological stack, marketing, R&D investments, ROI roadmap management, indirect distribution are complex and inaccessible for most companies.

We bet that by providing a common platform and reducing the software to « bite » sized, running, live service, we’ll enable re-usability, sharing and ultimately, billing through direct sales or marketplace.

🦄 Simplicity

There are too many ways to create software today. We created code.store in a way that you can focus only on your code, while we take care of the rest (some of the features in the list are still in the roadmap, but we are working hard to deliver them to you as soon as possible):

• containerization

• database modelling and management

• security

• GDPR

code.store is a rather opinionated platform, which means we have made a certain number of choices for you to simplify the development. However, we want it to be a platform built by developers for developers, and we are open to suggestions and would be very happy to hear from you in our community chat !

PS: If you've read it all, please about us!

Oops!🙀 Our team is working hard to build a great web UI that will help manage your services online. Join us at our community home to find out more about it and when it is going to be released: https://spectrum.chat/code-store

Coming soon!

Overview

When you include services to you project there might be a cases, when services should communicate with each other. code.store platform allows inter-HTTP communication

The goal of this section is to get you up to speed real fast. We are going to learn how to install and use the command line tools of code.store, how to create an account, and write a basic service! Let's continue 🚀

You know that we care about your time, so we created a local launcher for your services. But you also know that your services have a local database to store your objects. Let's setup a local Postgre database.

I love working with their simplest version: postgreapp. Go there and download it.

Launch the application. You have your local postgre database. You should see a small icon of postgre in your menu top bar.

Now you can go in any of your services folders and and edit codestore.yaml file. You should see something like that :

Change the database name, password, and username to the ones from

To test your connection, nothing more simple : execute in the root folder of your service cs dev command. You should see something like that :

Overview

code.store platform support middleware functions for REST endpoints. To avoid manual file creation allowed a command cs generate:middleware, which generate a template of middleware with handler method.

To generate middleware for your route just execute cs generate:middleware CLI command, select one of middleware type: request or response middleware type, specify name for your function and select route from the route list:

> cs generate:middleware

? Select position of middleware (Use arrow keys)
  response 
❯ request 

? Enter name of your middleware: permissions

? Select route to apply (Use arrow keys)

File ./demo_app/src/rest-middlewares/permissions.middleware.ts has been generated.

After command execution will be generated file permissions.middleware.ts in src/rest-middlewares directory:

More information about handler method and his params can be found in section.

Overview

code.store platform support file based REST endpoints. To avoid manual file creation allowed a command cs generate:rest, which generate an empty route template with handler method.

To generate REST route just execute cs generate:rest CLI command, select one of HTTP methods: GET, POST, PUT, DELETE and specify a new route name

> cs generate:rest

? Select HTTP method (Use arrow keys)
❯ GET 
  POST 
  PUT 
  DELETE 
  
? Select HTTP method GET

? Name of your REST endpoint hello

After command execution will be generated file get.hello.ts in src/rest directory:

More information about handler method and his params can be found in section.

Overview

code.store platform makes it possible to generate most of the necessary entities for comfortable development.

At the beginning of the journey, when creating a service, it is possible to choose the language of your future service. code.store platform will generate default "hello world" application.

Generation happens cs generate CLI command. During development, it is possible to generate entities such as:

Overview

By default, each service has different variables, which depends on the environment. For example, database environments, which available on the development environment may differ from the staging environment, and so on... For more information about environments, see the Environments section. Depends on service language, environment variables can be accessed in different ways.

To access environment variables using TypeScript or JavaScript language use:

Below, you can find information about available environment variables which code.store platform set by default.

Service Environment Variables

PROJECT_ID internal ID of the project on the code.store platform

ENVIRONMENT_ID name of the , where service deployed

SERVICE_ID internal ID of the service on the code.store platform

Database Environment Variables

Postgres Variables

DATABASE_HOST connection host

DATABASE_PORT connection port

DATABASE_NAME name of the database

DATABASE_USERNAME name of the user which can access to services database

Redis Variables

REDIS_HOST Redis connection host

REDIS_PORT Redis connection port

Language-based environment variables

TypeScript & JavaScript

NODE_VERSION node version, which deployed service used

Overview

code.store platform support . To avoid manual file creation allowed a command cs generate:resolver, which generate an empty resolver for your query or mutation which specified in schema.graphql file in src directory.

To generate resolver execute cs generate:resolver

Overview

To simplify authorization and authentication process code.store platform provide an opportunity to create an authorization handler for REST and context handler for your GraphQL API.

Authorization handlers released as middlewares and allows to implement custom authorization logic.

Overview

The bigger your system grows and the more libs or packages you integrate into your project, the more likely you are to face such a problem as dependency hell.

As a solution, code.store platform suggests relying on a simple set of rules and requirements that govern how version numbers are assigned and incremented. There are many approaches to software versioning and their interfaces, the choice is always up to the developer.

When you create a new service, by default, it deployed into private and demo and it's version is 0.0.1

Which version currently deployed?

To find out which version is in use execute cs service:info CLI command and select the service. You will find which versions deployed on private and demo environments.

On example above on the private environment deployed service with 0.0.2 version and 0.0.1 on the demo.

If you already include service to project, you can execute cs project:service:info CLI command, select project and service to display.

On example above deployed on three environments deployed next versions:

Create a new service version

To create a new version just push your changes using cs push CLI command. More information about pushing changes can be found in section. After pushing changes - a new version will be available on the private .

It's very important to increment service version after making changes to service. Actual service version is always available at package.json file.

Publish a new service version

After creating a new service version using cs push command - changes will be available only on the private .

demo - is the only place, where developed changes can be published. Changes from demo environment is available for including to the project or public .

To make a new version available - execute cs promote CLI command. This command will deploy changes from private to demo environment and makes a new version available for update/include into projects. Promoted version to demo environment is marks as LATEST

Manage service version inside project

When you include a new service to the - version from demo will be deployed. This allows adhering to the concept of public release of new versions to avoid unexpected system behavior. More information about including services to projects can be found in section.

Move service version per environment

After including service to the project - it's deployed only to development . To move service version to another environment use cs project:service:promote CLI command. It allows you to move already deployed version to another environment.

For example, if your project includes some service - you can promote only already deployed service version to another environments.

Update service version to latest

To update project service to latest version execute cs project:service:roll CLI command, where you can select project, environment where will be applied changes, service and version.

Select latest version if you need a latest available service version.

Rollback service version

To rollback service version use the same command cs project:service:roll and just select needed version and environment where to deploy needed version.

Create your service & GraphQL Schema

The service you are building is going to be consumed by your clients (real clients or frontend teammates) via an API (GraphQL), which your service is exposing. That is why we believe in the schema-first approach, where you are required to define an API (or a schema) first and then develop a backend that provides data for this schema (as opposed to a code-first approach where the schema is generated from the code you write). GraphQL schema (or API) IS YOUR PRODUCT! That is why everything starts with a schema at code.store.

Database generation

We strive to simplify your life, and so we are taking the complexity of database management from your shoulders and are g automatically from your schema. Whenever you add a new type, field, or modify the existing ones, our platform generates migrations and which you can use to write business logic in resolvers.

Promote your service to a private environment

When ready, push your changes to our cloud using the to our platform. code.store will check your code, containerize it, and deploy it to a private . You can then promote your service to the Demo environment, which is used to let every developer in your experiment with your and check if it corresponds to the needs of their .

Add a service to a project

Once created, your cannot be used per se in a production application or site, you need to add it to a . Projects represent applications or sites where your is used. Each service can be used in as many projects as you wish. You can use our web UI or to add your service to any of your projects. Every developer in your organization can create projects and add services to them. A is created when you add a service to a . It's an entirely isolated version of your service: it has its dedicated environments, database, and logs.

Sell your work to your clients for a monthly fee, if you want 💰

For each in a , you can define a rate-plan so that you can bill your clients monthly per service usage (price per call) or as a subscription. The core idea is to bundle together costs of building the service, its maintenance, support, and hosting in a single simple fee that your client pays. Up to today, you can sell and bill services to your clients only, but we'll be launching a public marketplace as soon as we have enough on-board service .

Overview

In order to secure public access to API of your projects and services - code.store platform allows you to restrict access using the request authorization mechanism and using access key

code.store platform provides an ability to restrict access using access keys, which serve to identify each request that is sent to your services. Access keys are generated by default when a service or project is created. Also, you can create new access keys for the purpose of separating access for clients manually.

Authorization

To authenticate your request just add a HEADER “x-user-authorization” to each request, where value of this header will be access key, which you can receive using cs service:info CLI command on the private environment or generate a new one using cs project:client:add command.

Below an example of authorization using curl command in your terminal:

Service access

Each service at the beginning is deployed in demo and private environment. But, there are different way to access your service.

Demo environment access

Demo environment is always public and can be accessed by any platform user.

Private environment access

private environment - it's a private space, where developer can personally run and test his code. In order to restrict access to the development process, a developer key key was created.

After service creation, you receive a developer key for your private environment. This key must be used each time when you call your service in a private environment.

If you forget your service developer key - execute cs service:info CLI command, select required service (or just navigate to service directory) and you will find it there.

Project services access

Developer key

By default, when you create a new project - you receive a project developer key. Using this key you can access any service deployed into your project on any environment. If you forget your project developer key - execute cs project:info CLI command, select required project and you will find it there.

Clients

There are cases when it is necessary to provide to the whole project or included in the project services to the client or third party person. code.store platform provides and CLI interface, which allows to manage client's access keys.

Using cs project:client CLI command you can add, list or remove client's access keys for your project and project services.

Clients access keys has a restriction: using this key client can access only production environment. staging and development environments is available only using developer key.

Create a new client access key

To create a new client access key just execute cs project:client:add command, select the required project from the list and specify client's email

List client's access keys

To list client access keys execute cs project:client:list command, select project form the list below and enjoy your client's list:

Revoke client access

To revoke client access you should remove client access key using cs project:client:remove command with CLIENT_ID flag.

🏠 Where my services are hosted?

code.store is cloud-agnostic, meaning we can deploy code.store on any cloud provider or even on-premises for Enterprise clients.

Services of all other plans are currently hosted on our AWS infrastructure (Frankfurt region at the moment, other regions are coming soon).

🦄 Who creates services?

You do it. Don't be lazy. 😈

💰How do I monetize my services?

There is no public marketplace yet. When you build new projects for your clients, you can create some part of those as reusable . Then you can sell them to your clients with a subscription or pay-per-use rate plan.

When you add a in a , you can set up a different price for each of your . You can then invite your client to this , providing his billing details. We'll generate the invoice for each client and collect payments for you. Each month you'll receive your combined funds collected from all clients in a single payment from us. Money time!

💵 How should I price my services?

You can bundle in a single monthly rate everything:

• your initial build cost (example: the 50 working days used to build the service)

• support and maintenance time (example: the 5 working days you spend every month on this service)

• hosting (code.store costs)

🗣️ What programming languages do you support?

At the moment we support only (which is the 2nd most loved programming language in the world 🤘 as per ). If you need a specific language for your , drop us a word .

🛢 I need a database for my service, how do I create one?

We provide a managed Postgres database for your services, but you don't have to worry about it as code.store creates and updates your based on the of your .

🧱 What is a service?

We call a service piece of code running on our platform that is accessed through a GraphQL API. You can learn more about our core concepts here.

🖼️ Where should I host my front-end?

We provide a platform to create and host back-end services that are accessed through GraphQL API. So at the moment, we are not focused on this particular feature, especially knowing that there are already many great services that can help host your frontend in the cloud.

However, this is something that is in our roadmap, and you can to help us prioritize it!

Overview

Each service has a default configuration file, which available by default, after new service creation. This configuration file named codestore.yaml and located in the root of service dir.

This file contains service configuration and used to:

• enable/disable PostgreSQL database

• enable/disable Redis database

• setup configuration for local development

• contains internal code.store's serviceId

Variables

serviceId internal code.store's service id

serviceConfiguration remote service configuration, which allows and contains the following flags:

• skipDatabase (false by default) boolean flag, allows to enable or disable PostgreSQL database

• enableRedis (false by default) boolean flag, allows to enable or disable Redis database

localConfiguration configuration, which allows to run local development service using cs dev CLI command and. Local configuration contains service, database (Redis, PostgreSQL) configurations which required if databases in serviceConfiguration are enabled. localConfiguration is contains the following properties:

• application

  • port a port where an application will runs

• database PostgreSQL connection config

Configuration versions

Enable/Disable PostgreSQL

By default, PostgreSQL - enabled. To disable PostgreSQL set skipDatabase: true of the serviceConfigurationobject and push changes using cs push command.

Enable/Disable Redis

By default, Redis - disabled. To enable Redis set enableRedis: true of the serviceConfigurationobject and push changes using cs push command.

Overview

code.store platform by default use RDBMS with and provides opportunity to generate models and migrations based on your schema.graphql.

is a powerful, open source object-relational database based on SQL and supports many of the features of the SQL standard.

Overview

From time to time becomes necessary to monitor the status and progress of a deployed application, look at the current application activity, or debug an error.

code.store platform provides an interface for working with report logs. By default logs contain information about the exceptions that the deployed application produces, service bootstrap and other things that the developer considered necessary to add as logs.

On backstage, as a log storage code.store platform used database, which allows to organize a quick search through the logs.

Overview

Environments are created for those cases when it is necessary to create a set of independent services, with own databases, which interacted with each other, in order to isolate the environment for development, testing, and release of service groups.

In service deployment, environments are a kind of isolation medium. Each environment unites certain sets of rules which describe components that it includes, namely: services, their versions, databases, routing traffic rules...

For convenience, we on the code.store platform creates several environments at once for the purpose of comfortable development and rolling out updates.

Installation

Overview

Managing sensitive strings such as passwords, API keys, and secret credentials — is just one of the steps in the quest for increasing security in a project. We understand this like no one else and provide an extremely easy and secure way of managing secret variables.

All secret variables are stored in Vault, secret storage from HashiCorp organization, which provides a high-security level thanks to its architecture and secret engines.

Service Secrets

For convenience, all variables that we specify for the service are available as environment variables. In order to add a new variable for the service, you can use the CLI interface, which can be found in .

Service secrets are secure key-value storage, which syntax is available using cs secret command.

Add a new service secret

To add a new secret variable just execute cs secret:add command with flags which next flags:

• -k key of the secret variable

• -v value of the secret variable

• -s service ID

Information about all supported flags can be found on section.

Below is an example of adding the FOO variable with the BAR value to the existing service with ID: MY_SERVICE. For clarity, we will use a service that is deployed in a demo environment.

Successful result of the command execution will be:

That’s it! Now, variable FOO will be available as an environment variable after container reboot. Now, you can access it in your code.

Access a new variable in code

For example, to access variable using TypeScript use process global variable:

List service secrets

Update service secret

Remove service secret

Project Service Secrets

Using the same command syntax we can add an environment variable for any project services.

-p flag allows adding a variable on the project level.

The FOO variable is now available inside the MY_SERVICE service, which is included in the MY_PROJECT project.

Please note: MY_SERVICE service is already included in MY_PROJECT project.

But what if my project includes many services that are deployed in different environments? Would be inconvenient to prescribe a separate set of secret variables for each service, so we implemented inheritance.

Inheritance

There are cases when we need to specify only one secret variable for all services which includes in the whole project. In this case, we can just execute cs secret:add only with -p project flag.

Let's imagine that we have an empty project with ID: MY_PROJECT, which includes three services with ID's: A, B, and C. They, by default, deployed on three project environments: development, staging, production. For more information about environments, see the section.

Project level variables inheritance

Let’s add variable FOO with value BAR to project MY_PROJECT, which will be available for each service on each environment inside MY_PROJECT project.

Successful result of the command execution will be:

As you can see, the Source of a variable - is a project, where we just added a new variable. From this moment, we can access FOO variable from each service, in each environment, which included in our project. In the diagram below, the services that have access to the value of the FOO variable are highlighted in green:

Environments level variables inheritance

We may face a case when you need a different secret variable value on some service or on the whole environment. This isn't a problem, cause we can just override the value of the variable, using the same cs secret:add command, specifying for which environment/or service we should apply it.

For example, if we specify the FOO variable with value BAR2 for a project MY_PROJECT from the previous example and just set flag -e (environment) with value development, we override this value for each service in the development environment.

Successful result of the command execution will be:

In this case, the Source displays the current variable source and shows that FOO variable has BAR2 value for each service, WHICH includes in the project MY_PROJECT, and deployed on the development environment. In the diagram below, the services that have access to the new value BAR2 of the FOO variable are highlighted in blue:

Service level variable inheritance

In case, when our service requires another secret variable value - we can just override it. To override it - just specify -s flag with service ID, let it be service A for example, and a new value of FOO variable is BAR3.

Successful result of the command execution will be:

In this case, service A will obtain a new value of FOO variable. In the diagram below, the services that have access to the new value BAR3 of the FOO variable are highlighted in yellow:

When you create a service on code.store, it is accessible via a unique API endpoint and you'll need to use GraphQL in order to interact with this endpoint.

While you'll find all the details on GraphQL site, we've prepared you a short summary of GraphQL basics here.

What is GraphQL ?

You can think of GraphQL as of SQL but for API (it is a very loose and far-fetched analogy, but it should deliver the message).

GraphQL is an API standard that provides a more efficient, powerful and flexible alternative to REST. It was developed and open-sourced by Facebook but now many companies, including us, support and rely on GraphQL. We do think it will become worldwide API standard very soon.

code.store GraphQL service is created by defining types and fields on those types, then providing resolvers for those types.

GraphQL types

GraphQL has its own type system that’s used to define the schema of an API. The syntax for writing schemas is called (SDL).

Here is an example how we can use the SDL to define a simple type called Product:

There are 5 built-in scalar types with GraphQL: Int, Float, String, Boolean and ID. Scalar types, as opposed to object types, point to actual data. The ID type resolves to a string, but expects a unique value.

Enumerations

Enumeration types allow to define a specific subset of possible values for a type. In the previous example, the Category enum type can take a value of Clothes, Shoes or Watches and anything else will result in a validation error. We need to update our example providing definition of our enumeration category :

Type modifiers

Modifiers can be used on the type that a field resolves to, by using characters like ! and […]. Here’s a breakdown, using the String scalar type as an example:

• String: nullable string (the resolved value can be null)

• String!: Non-nullable string (if the resolved value is null, an error will be raised)

• [String]: Nullable list of nullable string values. The entire value can be null, or specific list elements can be null.

GraphQL queries execution

GraphQL doesn’t just specify a way to describe schemas and a query language to retrieve data from those schemas, but an actual execution algorithm for how those queries are transformed into results. This algorithm is quite simple at its core: the query is traversed field by field, executing “resolvers” for each field.

The payload of a GraphQL query (or mutation) consists of a set of fields. In code.store, each of these fields actually corresponds to exactly one service that’s called a resolver. The sole purpose of a resolver function is to fetch the data for its field.

When code.store receives a query, it will call all the functions for the fields that are specified in the query’s payload. It thus resolves the query and is able to retrieve the correct data for each field. Once all resolvers returned, the server will package data up in the format that was described by the query and send it back to the client.

Queries to retrieve data & mutations to push data

Queries as mutations are the methods or functions of your API. Both have arguments and can return scalars or objects. The difference between the two?

Use queries to query data from your API. With query, you do not modify your model (even if you can, you should not).

Use mutations to update or create things in your service model. Mutations are also methods or functions of your API and can accept arguments. Use them to modify your model.

A mutation can contain multiple fields, just like a query. There's one important distinction between queries and mutations, other than the name:

While query fields are executed in parallel, mutation fields run in series, one after the other.

This means that if we send two incrementCredits mutations in one request, the first is guaranteed to finish before the second begins, ensuring that we don't end up with a race condition with ourselves.

Overview

code.store platform supports GraphQL and allows you to set up your GraphQL API in the quickest way. To make a developer's life easier code.store platform:

• by default runs GraphQL Apollo Server

• provides an opportunity to generate database entities based on graphql.schema

• generate resolvers for your queries and mutations

• secure your GraphQL API from massive complex requests and DDoS attacks, and allows you to configure GraphQL query costs

Basic information about GraphQL can be found in section.

Endpoint

By default, code.store platform runs and GraphQL playground available via /graphql endpoint.

Local development:

Remote address:

Schema

When you create a new service, we code.store platform generating it with default schema.graphql file, which contains services GraphQL schema. You can find it in src directory of the generated project. Generated file contains a simple helloWorld query:

It's a very basic schema of an API that has a single Query called helloWorld (which doesn't accept arguments) and which returns a single output of type string. You can query it using GraphQL playground, which available on /graphql endpoint or execute next command using CLI:

Please, replace service_url_hash on your service URL hash, which can be found after cs service:info command execution. After helloWorld query execution we should get "Hello, World!" response in our terminal:

Resolvers

Each field, query or mutation, which we specify in schema.graphql require resolver. A resolver is a function that's responsible for populating the data for a single field in your schema.

Handler for all queries and mutations, which described in schema.graphql file should be placed to src/resolvers directory. Each resolver file of your query or mutation should be named the same, as it declared in graphql.schema and placed the appropriate directory src/resolvers/queries for queries and src/resolvers/mutations for mutations.

For example, in generated service template you can find, that query helloWorld in schema.graphql have resolver src/resolvers/queries/helloWorld.ts

Context

Each resolver can optionally accept four positional arguments:

parent returns value of the previous resolver in the resolver chain for this field's parent

args an object that contains all GraphQL arguments provided for this field. For example, when executing a query: query{ user(id: "4") }, the args object passed to the user resolver is { "id": "4" }.

context an object shared across all resolvers that are executing for a particular operation and has ResolverContext type.

As you can see, context allows receiving database connection and provide access to request object, which includes such objects as headers, method, url...

info contains information about the operation's execution state, including the field name, the path to the field from the root, and more.

Overview

code.store platform allows you use two database types for your services:

Overview

Projects are the essence of the code.store platform, which has the ability to contain many services.

Projects serve as an isolated environment for services groups. Any project can contain one or more services, and available within the organization the user belongs to.

In order for the service to be publicly available, it must be included in the project, since the code.store platform guarantees high availability and scalability only in a production environment. For more information about environments, see the Environments section.

Create a new project

In order to create a new project, you need to execute cs project:create command and provide information about your service. Below an example of cs project:create command execution:

Successful result of the command execution will be:

After successful project creation, an access key to the development and staging environments will be issued in the command output. Information about authorization using the provided key can be found in section.

When creating a new project, by default, the code.store platform will create three environments: development, staging, and production. For more information about environments, see the section.

Let's make sure that the project has been created by running the cs project:list command.

Project ID displays ids of all projects that available for user. Please, note, that ID is lowercase.

Services count of included to project services.

Author email of the project creator.

Description description, which user set, when creating a project.

After creating a project, it will be available to all members of the organization to which the user belongs.

Include service to project

By default, there are no services in the project. To add a new service to the project just execute cs project:service:add command with two arguments: projectID - where service should be included and serviceID - id of service, which will be included.

For example, let's include service demo_app to the my_project project:

After command execution, the service is being to deploy to the development project environment.

To monitor service deployment status just execute cs project:service:info command and select the project and service.

cs project:service:info command output will display environments, where service is deployed (in our case service just added to project and deployed only to development environment), deployed service version, developer key, and the service URL.

Promote service

After adding a new service to the project, it becomes necessary to deploy it not only to development but also to staging and production environments.

To promote service per environments available cs project:service:promote command. After command execution, you will be able to select the project, service which already included into the selected project and environment, where service should be deployed.

In the example above, we promote service with ID: demo_app, which already included to project with ID: my_project to the staging environment.

Using this approach, you can deploy the service to a production environment.

Update service version

To update service version just re-use cs project:service:promote command.

It is necessary that the service was previously updated on the demo environment. For more information about environments, see the section. About versioning see the section.

Exclude service from project

Delete project

🧱 Service

Service is the most crucial concept in code.store. It is a stand-alone web-service that can be (re)used in projects. What defines a service:‌

• GraphQL Schema: you start by defining a GraphQL API describing types, queries and mutations of your service

• Code: actual code that is invoked when your GraphQL API is called. There is a specific structure and naming convention for your files which we describe in our Quick Start guide.

• Database: based on your GraphQL schema, there is a where you can store your data. We take care of its creation, updates and whole management including automatic migrations in case of any change in your .

• Documentation: when you create a new service you need to explain what functional problem your service solves, how does it solve it and what is its functional domain (e-commerce, content management, logistics, etc.). You can also add some free #tags to help users search for your service.

What makes a perfect code.store service :

• Independent: it does not rely on anything else to function (no external APIs or services or software is required to use it).

• Isolated: by all means, it should avoid communication with external systems (except for connectors)

• Autonomous: it's shipped with a database and file storage if any of those are required.

Some examples of what we call service : ‌

• Shopping cart of an e-commerce site

• Meeting rooms booking system

• Email sending service

• Credit card payment

Each service has 2 : private - used by service for their development and tests, and demo, used by developers to test the service

🚧 Project

A project is a particular app or website, where you reuse your existing services. It might be your e-commerce project or a logistics mobile application or business web-app. Because you pay us only when we help you save money, we bill you only for live (those that are included in Projects).

Each time you add a service to a project, we create a separate, isolated instance of your . Each service reused in a project has its own , , logs, and billing.

♻️ Service instance

A service reused in a is an instance of a you've created. Each time you add a service to a project, you create a service instance. Each instance of a service is isolated, runs its own set of 3 (dev, stage, prod) and is accessible through its GraphQL .

⚛ Schema or GraphQL Schema

A schema or defines and describes your . It uses with some additional directives. You have to define 3 main things:

• : they describe objects your service is manipulating (Product for a cart, Meeting Room for rooms booking engine or Client for a CRM service).

• : at its simplest, GraphQL is about asking for specific fields on objects. It's a shorthand syntax where we omit both the query keyword and the query name, but in production apps, it's useful to use these to make our code less ambiguous.

• Mutations: most discussions of GraphQL focus on data fetching, but any complete data platform needs a way to modify server-side data as well. So mutations offer your API consumers a way to create and update objects manipulated by your service (i.e., addToCart(productSKU))

📁 Model

A model is a description of the way your service's database is structured. You cannot directly modify your service's model, which is generated based on the GraphQL schema of your service. We generate TypeORM entities in your service files directories here: /src/models/

‌ You can access the structure of your database or model through the web-UI data viewer too.

🛢Database

Each has a managed database related to its . Each time you add, remove or update a type or a field, we automatically update and migrate your service's database. We use PostgreSQL to run your service's database, and we generate TypeORM entities to help you access your data from your service's code. You can also access your database, through ou data viewer web-UI.

🍱 Environment

An environment is an isolated, running copy of your service. Your is automatically shipped with 2 environments: private and demo. Private is visible only to you, the service , while demo is used to test the service by anyone in your willing to use it on their . It's also demo environment which is used in web-UI service page where users within your can use the playground to experiment with your service.

As soon as you reuse a in a , you create a and 3 environments for this particular service in this particular : dev, stage and prod. Each environment has its own , , logs and other stuff. Be careful though, only prod environment is suitable to be used, well... in production, others (dev, stage, private, demo) have quotas and limitations and are not scalable.

Of course, you are not obliged to use any of those environments, and you can push your service to prod as soon as it's ready. However, first of all, it is not considered to be a good practice, and secondly, you may want to match the environment of your service with that of your front-end.

👷‍♀️Maker

If you read this documentation, you're a developer. We needed to distinguish developers who create from those who use them in . It's not a role or hard distinction, and you can be both consumer and maker of services within your . So to make it clear, we call maker the developer who created a .

🤷‍♂️Client

When you enable billing on your , you're prompted to invite a client to your . So on code.store, a client is an who pays for used in a project. It's entirely optional to have clients. If you don't sell your services and use them internally, you will not need to deal with clients.

🏢Organization

It's an entity where projects, services and users are attached to. All services you create as a maker are visible to all users within your organization. Each user of code.store is always attached to an organization.

⚓ Endpoint

It's the URL you need to call to connect to your and execute queries. There is an endpoint for each of your . There are endpoints used to test a service before using it (private and demo attached to each service created by your ), and there are 3 endpoints for each inside each : dev, stage and prod.

Overview

At the moment, code.store's platform supports a simple file-system-based routing of REST API endpoints.

REST endpoints are based on framework, so you can use all Express features to build your application. Using REST-based on you are able to create endpoints of different methods (such as GET, POST, PUT, DELETE, PATH…), define your route paths, handlers, work with route parameters, define your middlewares…

code.store platform simplifies the process of creating endpoints and their handlers using flexible configuration and provides an ability to generate a couple of entities.

In some projects, you'll need to include some NPM packages and run them as a service. Let's take an example and create a chess server using

We consider that you're familiar with code.store CLI, you have an account and you know how to create a new service. If not, follow our .

Step 1: Create a new service

Check that you're authenticated :

If you receive following error message, that means you're not authenticated and you'll need to execute

Overview

Services - is the main entity that you operate on when working with the code.store platform. These are backends that you, members of your organization, or public users of the code.store platform creates.

One of the key features of our platform is the reuse of services. Since the service doesn't belong to any specific project, you can reuse the services that are available to you.

For convenience, the code.store platform provides the ability to develop your services in various languages:

• TypeScript

Currently, we are actively working on adding support for different languages and frameworks, such as: Go, PHP, Python, Java, C#... so soon you will be able to see support for your particular technology.

Using the CLI or web interface - you can create/edit/update/add to projects/delete your services. Below are examples of how this can be done.

When service is created - the platform automatically deploys it to private and demo environments. For more information about environments, see the section.

private environment - created exclusively for you, with the purpose of developing and testing your service, when the demo - is a public environment, in the context of your organization (or marketplace, if you wish to publish your service in mass and make some money on it)

New Service Creation

In order to create a new service, you must have an account on the platform

Web interface

You can create a new service using the web interface by going to by clicking on the “create service” button located at the bottom of the screen. Fill out the service creation form and click on the CREATE button. After that, the service will be available on the general list on the services page.

It takes some time for the service to be available, in general, the creation process takes less than a few minutes, during which we create a working instance of your future service, collecting an image for you, and deploying it in one of the k8s clusters. We are actively working on the platform and in the future, the process of creating service will take no more than 10 seconds.

CLI

In general, creating a service through the web interface or through the CLI is no different, except for the visual design. Perhaps, as a developer, the way of creating a service using the CLI will be more comfortable for you, since at the stage of creation you will receive more information about what is happening “under the hood”

In order to create a new service, you need to have a pre-installed CLI and be authorized on the platform (see guide)

First, go to the directory where the folder with the initialization template for your service will be created, for example, let it be your home directory.

Then, just execute the :

Using the cs service: create command, we initiate the process of creating a service, during which it will be necessary to answer the following questions:

• ? Service name:

• ? What problem are you solving?:

• How do you solve it?:

• Choose business domain using arrow keys

After that, you will see the progress of creating a new service, during which we copy the starting project template, build the image, and deploy it to our k8s cluster.

We are actively working on the platform and in the future, the process of service creation will take only a few seconds.

After successfully creating the service, you will receive a message with links and secrets. Here an example of the output:

You can check its performance by following the links that you received when creating the service. These links lead to the GraphQL playground, which is available by default for every new service.

Please note that your service was deployed on two private and demo environments at once. For more information about environments, see the section.

You also receive a developer key for your private environment. This key must be used each time when you call your service in a private environment, just by adding HEADER “x-user-authorization”. In order to restrict access to a service that is under active development, you should use an authorization. The built-in mechanism for accessing and authorizing your services can be found in the section.

After creating the service - the code is available at the same dir, where you execute cs service:create command, in a new folder, which has the name of your service, that you specified while creating.

File Structure

The root directory contains two files and one folder:

• codestore.yaml – the file that contains the configurations of your service, you can learn more about the settings on the service page

• package.json – it is a standard NPM configuration file. Feel free and add any NPM packages you like using npm install {packageName};

• src/

Let's dive into the src/ directory:

• schema.graphql – contains a schema of your service;

• data/ – folder that contains entities, which required to work with the database.

• data/entities – this directory contains TypeORM entities. You can automatically generate TypeScript classes for your database tables using

Most of the things for working with the database, such as migrations, Typeorm entities, can be generated using the generator built into the CLI. The principles of models and migrations generation can be found in the section.

Local development

To simplify the local launch of the service - available simple command: cs dev. After executing, on the backstage will be installed all dependencies (npm i), compiled typescript code (tsc), validating GraphQL schema, queries, and mutations, and applied functions.

Running this command will install all the necessary dependencies with package.json, compile the code (for this we use tsc), validated GraphQL schema.

After successful execution of the command, the service will be available at the link: http://localhost:3000/grpahql Please, make sure that 3000 port is free, before launching command.

Below is as an example of successful execution cs dev command

Service update

Create a new version

Each service from time to time has to roll our new updates. After changes have been made to your service code - we can roll updates to the . To publish a new version you have to use cs push command.

Displayed service version will take from package.json file.

Following our concept, by default, the service will be updated on the private environment.

Pushing updates

Using the cs push command - you publish your changes. When executing this command, you will specify release notes, which will serve as information about what exactly changes have been made. Below is as an example of successful execution cs push command:

As you can see, on backstage we compiling your code using tsc, and validating the schema, so you can be sure - changes you made are valid. If something went wrong - you will see an error message and pushing will be interrupted.

In general, working with the cs push command can be thought of as a git command with validation and pre-compilation of your code. In the future, we will provide access to your code through the GIT repository, but at the moment, you need to take care of this by yourself.

Promote new version to Demo environment

After pushing changes to Private , in order to further distribute a new version of the service to projects, it becomes necessary to publish the changes. To publish changes just execute cs promote command.

Service promotion from private to demo environment will create a new service version. To learn about environments and versioning concepts follow and sections.

Validation and compilation

Each time when you push your code using cs push command - we compile and validate your code. If you develop your services using local development using cs dev command - you can be sure that everything will be OK.

Each push of your updates trigger compilation based on tsc (TypeScript compiler) and GraphQL schema validation. If something went wrong - you will receive an error message.

Interfaces

The code.store framework provides the ability to create both REST and GraphQL interfaces.

REST

REST interfaces - is a simple file-system-based routing of REST API endpoints based on framework. How to create REST endpoints, handlers, middlewares described in section.

GraphQL

is an API standard that provides a more efficient, powerful, and flexible alternative to REST. We understand it like no one else and provides an opportunity for full-cycle data management of your GraphQL API. With code.store platform you able to:

• be sure, that you schema and code always valid

• generate database models ( entities) based on your GraphQL schema

• generate migrations to your PostgreSQL database

• generate handlers to your queries and mutations

How to use GraphQL described in section. How to generate models, migrations, resolvers... described in section.

Service info

To display information about your service just execute cs service:info command inside service dir.

Command execution result will be displayed with information about deployed on the demo and private environment service version, deployed date, developer key's and service URL's.

To download and install CLI, follow the instructions here.

Synopsis

To get a list of all commands, call cs help:

Basic usage

Authentication

To be able to use the CLI you have to login into your code.store account. To do that use the following command:

cs login will try to authenticate through the browser (it is going to open the default browser in your system).

At any time you can check under which user you are being authenticated:

In order to finish your session and logout use the following command:

You can also use short aliases of the above commands: cs login, cs whoami and cs logout.

Services

List

The cs service:list command that can be shortened to cs service:ls, and is used to provide a list of your along with their status.

Create

Create a new service by calling cs service:create which will display a wizard and ask for some necessary information in order to create a service.

Info

Displays more detailed information about the service:

Delete

Deletes the service. Deletes it for real, so please make sure that you are sure about what you are doing.

Dev

Launches a service locally. Requires PostgreSQL and configuration in codestore.yaml.

Generate

List

List the services in your organization. You can also use a short version of this command: cs service:ls.

Note: don't be surprised to see some services when you just created an account as those may be the services created by the colleagues in your organization.

Logs

Print out the logs of your service. Available options are:

Promote

Pushes your service from Private to Demo environment.

Pull

Downloads a service to the current directory.

Push

Push local changes to Private environment.

Projects

In order for your to be published, they have to be added to . Projects can be created and managed either by using the web-site or via CLI.

Create

Launches a project creation dialogue:

Delete

Deletes the project but only if there are no existing services inside it. Make sure that you remove all services from the project before removing the project itself.

List

Get a list of all your projects (you can also use a shorthand alias cs project:ls:

Services inside the Project

In order to manage services inside your project, you can use cs project:service sub-commands. Most of the commands are quite similar to those of cs service.

Add

Adds an existing service to a project. Requires a Project ID as an argument.

List

Lists services in your project:

Info

Displays detailed information about project's service, in a similar way to cs service:info.

Promote

Promotes your service inside the project between Development, Staging and Production environments.

Remove

Removes the service from the project.

Generate

This group of commands generate scaffolding (templates) of some important files.

Handler

Generates auth and context handlers.

Read more about the usage of those handlers in our .

Models

Generates the entity models and database migrations for your GraphQL types and puts them into src/entities.

Resolver

Generate a template of a GraphQL resolver:

REST

Generates a template of a REST API endpoint handler:

This guide covers writing custom middleware for authentication purposes.

Overview

You can tell code.store to pass every request (query or mutation) marked with @auth directive via your custom middleware. In a nutshell, it looks like the following. Imagine, that you have two queries:

Here is what happens on each request to one of those queries:

What happens is that all requests marked by @auth directive will pass via auth.handler.ts first and the context argument passed to the subsequent resolver is going to be concatenated with the return result of auth.handler:

That's not very complicated so let's build a simple example using this information!

Very simple example

For the sake of simplicity, we are going to use the code from our but essentially any other working service (including the newly created one) will suffice.

Let's take a look at our schema first:

As you may see, we have restored the helloWorld query, we also have restored the src/resolvers/queries/helloWorld.ts file too.

Let's modify our schema by adding the directive declaration and by marking one of the requests as @auth:

There are two things that happened here:

1. We added a declaration of the directive to the top of our schema.

2. We marked two of our requests (query allPosts and mutation createPost) with @auth directive, which means that we will be able to create and see the posts only as authenticated users. Neat!

At the moment, this @auth directive won't do anything, so let's add middleware and implement a very basic authentication model.

First, generate the handler file by running the following command in your service directory:

This is what you will see inside the file (I removed the comments to save screen-space):

The typical authentication flow is like the following:

• the client (your front-end or another service) will send a GraphQL request by passing some sort of authorization token in a specific header (typically it would be 'Authorization' header);

• your middleware will parse the token and validate it (against another service, or by interrogating the database with active sessions, etc);

• in the case when the token is not valid, your middleware will throw an error;

Say no more, let's implement a very basic authorization, that is going to check the Authorization header and will compare it with two pre-defined tokens:

I hope that it is really straightforward what we do in the above code: we react on two predefined tokens (it's really hard to call them tokens, to be honest 😬), based on which we will assign the permissions or in case if it's missing, we'll throw an error.

Next, we should somehow react to these permissions in our resolvers. Let's see how exactly we might do that:

This is what has changed comparing to the code from our , we added a small if condition that checks the permissions in the request context argument:

Let's do the same for createPost.ts resolver:

That's it! We can now test how our changes impact the behaviour of the service.

Testing

Let's test this baby! First of all, quick go-through to see what we are actually expecting:

1. query helloWorld should work as before, without any Authorization header (or with it);

2. query allPosts should return an error if the header is not specified;

3. query createPost should return an error if the header is not specified, or if the write permission does not equal true.

Let's test all these three scenarios.

1. query helloWorld should work as before

OK, so that worked as expected. Moving next.

2. query allPosts

You shall not pass indeed! Let's try to add the correct token header to our request:

This time it worked as expected. Let's move on to the final part.

3. mutation createPost

Let's try without the token first (or with the user_token, the result should be the same:

Bang! 💣Let's add the correct token now:

This time, it's a success.

Conclusion

In this short tutorial, we wanted to show you how to put in place a basic authorization system in your service. The idea was to show the capabilities of our SDK on a simple example, but the same approach could be applied to authorization with external systems like AWS Cognito or Auth0, as well as with the dedicated service on code.store.

This guide will introduce some basic code.store concepts like services and schema generation using CLI. The goal of this quick start is to get you up and running fast, so let's not waste any time and start!

Create code.store account

If you haven't done this already, then .