This page is an example of an “engineer’s guide”: just like a “user’s guide” tells you how to install and start using a product, the “engineer’s guide” tells you how to start developing a product.
You would keep this document in addition to your reference documentation containing all the information. It is an easy entry point for new developers, onboarding engineers, people who want to contribute to an open-source project, etc.
Strawberry is a program that takes the specifications from the customer and brings them down to the software engineers. This Engineer’s Guide tells you what you need to know to quickly be able to run and make changes in Strawberry.
Strawberry comprises several services written in Go with an Angular2 frontend. It uses gRPC for RPC.
Strawberry is developed by the Strawberry team. Contact us at #strawberry or see our team page at http://strawberry-team.
The Strawberry backend services reside at SRC/code/straw and the frontend at
SRC/web/straw.
Deployment configs are at OPS/deploy/straw and monitoring/alerting configurations live in
OPS/mon/straw.
You can run Strawberry on your workstation with the following command:
$ code/straw/run.sh
This command will compile Strawberry from the source and start a self-contained Strawberry stack on your computer, which you can manipulate at will. The script will display the URLs to access the frontend and the services. Pressing Ctrl-C will stop all the programs cleanly.
By default, the script binds its services to ports in the range 8000-8005. You can change this with the
--port flag.
You can use the --debug flag to enable remote debugging. It uses ports 5000-5005 by default, but
you can change this with the --debug_port flag.
You can deploy a personal instance of Strawberry with the following command:
$ clusterop deploy/straw/dev/berry.cfg up
The clusterop command will display the name of the cluster where the deployment happened and the
names of the jobs, which you can use to access them.
If you don't have any quota in the default cluster or you want to deploy to several clusters, you can use the
cluster var to specify a cluster name.
Only one replica is deployed by default, but you can use the replicas var to deploy more.
You can also override the default job name prefix with the name_prefix var.
Example:
$ clusterop deploy/straw/dev/berry.cfg up --var=replicas=3
Remember to use clusterop down to stop the job when you have finished working with it.
The code for the services lives in SRC/code/straw.
This directory contains the following subdirectories:
cmd — the entry points for the services.common — data and interface definitions, as well
as code that's shared among all services.webservice — provides the API endpoint for the web
frontend. All requests from the browser are received here.datastore — data storage service.notifier — the notification service.The cmd subdirectory contains one subdirectory for each service program, including a file with
the corresponding program's main function and its flag definitions.
The common subdirectory contains a proto subdirectory containing protocol buffer definitions and
several directories with data validation code, data access code, etc., common to all services.
The directories for the different services are relatively
dissimilar, but they all contain a service.go entry
point and a doc subdirectory with specific
documentation for that service.
The primary BUILD.bazel file is in SRC/code/straw, defining the binaries and
deployment packages. Targets in this file may depend on any other targets. Targets in services'
subdirectories may only depend on other targets in the same service subdirectory or in the
common subdirectory: dependencies between services are forbidden.
The frontend code lives in SRC/web/straw. Blah, blah, blah.
The deployment configs reside in OPS/deploy/straw. They use the common templates blah, blah,
blah.
Here are some common errors you could encounter when executing the program locally.
You already have a service running in ports 8000-8005 or 5000-5005. Use the --port or
--debug_port flags to choose a different port range.
You may get this error if you tested some schema changes locally and then abandoned them: the migrator cannot
recognize your current schema. The easiest solution is to delete /tmp/strawstore and rerun.
If you have questions or suggestions, contact us at #strawberry. Our team page, which contains more documentation, is at http://strawberry-team.
Copyright 2024 Jacobo Tarrio Barreiro. You may use this document as a template or model for your documents; no attribution is required.