How Tokay is organized
Tokay is structured around the problems that appear as an app grows. Related parts need to work together, while unrelated apps need clear boundaries. Workspaces, Projects, Services, and Code give you the tools to set up your app in a way that works well for you. Here is a quick rundown of what each one does and why it exists.
Last updated
A Project decides what gets shared
Think of a Project as one app or system. When you add something new, ask whether it should work with what is already there. If it needs the same data or should be available to the same people, put it in the same Project.
Putting Services in the same Project lets them use the Project's databases and secrets. They can also talk to each other over a private connection that Services in other Projects cannot use.
The Project also sets who can use its deployed apps. An internal dashboard and its API usually belong together when the same coworkers need both. A public site belongs in another Project when anyone should be able to open it. This is separate from who can manage the Project in Tokay.
A Service is the part that runs
Most apps have parts that run differently. A web app waits for requests, while a background worker may keep running all day. Tokay makes each part a Service so it can be deployed on its own.
Some Services receive traffic at a URL. A Service without a public URL may run on a schedule or stay alive continuously. See Which service type is my code? for how Tokay handles each kind.
Each Service keeps its own deployment history and logs, so a worker failure can be diagnosed and redeployed without replacing the web app.
Code stays separate from what runs
Tokay keeps your source separate from the Services that run it. Every Service runs from one codebase, while the same codebase can supply several Services.
A repo containing a web app and worker appears once as Code. Each part becomes its own Service and can be updated independently.
Code belongs to the Workspace rather than one Project. A staging Project and a production Project can use the same repo while keeping their data and configuration separate. Deleting a Service does not delete its source.
Your Workspace holds everything
Your Workspace is the home for everything you run on Tokay. It contains your Projects and Code, and it is where you add people who help manage them.
Every Workspace has one dedicated virtual machine. The Services and databases inside all its Projects run there and share its reserved capacity, so creating a Project does not add another server. See Your server for how that shared capacity works when your apps need more room.
If someone else needs to help manage your apps, add them to the Workspace and decide which Projects they can access. See Workspaces and members for how that works.