HAMY

CloudSeed Quickstart (Fullstack F# app in 10 minutes)

Date: 2024-01-03 | create | tech | business | cloudseed | fsharp |

CloudSeed is the F# project boilerplate I've built over the past several years. Its goal is to make building F# apps easy while providing a robust foundation for scale. I've used it in most of my projects over that time - tweaking, refactoring, and overhauling aspects of it as I discovered better ways of doing things.

In this post we're going to quickstart CloudSeed - everything you need to know to get up and running in ~10 minutes.

Q: How can I get up and running with CloudSeed in 10 minutes?

Answer

CloudSeed provides a "seed" for building 3S (Simple Scalable System) apps with F#. It aims to make getting started developing extremely easy while providing a strong foundation for any scale.

CloudSeed - System Design

To accomplish this, it provide sane defaults for the primary components every app needs:

This comes out to 2 containers running locally for an authentic development environment and we'd expect you to deploy just the F# app to prod where it would connect to your production database.

  • App - The F# app serving Frontend and Backend functions
  • [Local Only] Database - A local database to develop and test your app e2e including all data operations (pre-configured with Postgres)

This setup allows you to quickly clone, build, and scale.

In the rest of this post we'll walk through how to set up CloudSeed on your own machine so you can start building.

Dependencies

CloudSeed aims to minimize dependencies but there are a few we need to get started.

Required Dependencies

CloudSeed requires containerization infrastructure on your computer in order to run. We utilize containerization to minimize the amount of other dependencies / configuration you need to get setup before you can start building / deploying your app.

Docker - We're using Docker for containerization. It's got great reviews and ecosystem support which makes it a good choice for most apps.

Docker Compose - We're using Docker Compose for container orchestration. Now this is a bit overkill as we're only really using it to orchestrate the local database for your App and Tests. But I think this is critical for providing an authentic development environment for building robust apps quickly so I think it's worth it.

On providing authentic dev environments: The way I look at it is - if you cannot develop in an environment that is authentic to the one it is supposed to live in (prod), it is very hard to be confident that it will work as expected. So we should aim to make our dev environments as close to prod (maybe even prod) as possible - in the end all code gets tested in prod.

You don't need these installed but I would highly recommend it to improve your experience.

dotnet - The official .NET CLI for interacting with your app (F# runs on dotnet). This is very useful for restoring your app or adding / removing packages.

Ionide (or equivalent) - This is the F# editor plugin that provides a lot of nice things like intellisense and red squigglies when you have an error. Ionide is the one I use with VS Code but most mainstream IDEs have a similar plugin.

Running CloudSeed

Okay with our dependencies installed we're now ready to start running / building our CloudSeed F# app.

Note: All of these instructions are also available inside the repo's README

Get CloudSeed

Once you've purchased CloudSeed you will get access to the CloudSeed GitHub repo.

git clone that onto your computer.

Running CloudSeed

Now that we've got CloudSeed, open a terminal in its directory.

We'll spin up both the F# App and the local database containers with this command:

docker-compose down --remove-orphans && docker-compose build && docker-compose up

This command:

  • Kills any existing containers
  • Rebuilds these containers (to ensure we capture any changes you've made)
  • Spins up the new containers

By default, the app will be listening on these ports:

  • App - localhost:5001
    • Verify at localhost:5001/sentinels
  • DB - localhost:5002

You'll see output in your terminal so you can tell if it worked or not. We'll go over some example endpoints you can explore in the next section.

Testing CloudSeed

Before we do that, let's show you how to test things. CloudSeed comes equipped with a few tests covering its example domain to show you how you can build your own.

The command to run our tests is very similar to running our app - we're just specifying a different docker compose file which builds our App.Tests project instead.

docker-compose -f docker-compose.test.yml down --remove-orphans && docker-compose -f docker-compose.test.yml build && docker-compose -f docker-compose.test.yml up

Similar to the above command, this:

  • Kills any existing containers
  • Builds new containers
  • Runs the new containers

Example App

That's all you need to know to get you started but I also wanted to provide some examples to show you how to do common things. To this end CloudSeed ships with an example domain called Sentinels which just builds some CRUD frontend, data operations, and domain types to give you an idea of how you might build with these technologies.

You can see the frontend at localhost:5001/sentinels

The code is split like this:

  • Domain - SentinelDomain - The domain types
  • ServiceTree - SentinelServiceTree - The types we'll use for dependency injection
  • Persistence - SentinelPersistence - Handling the Entity Framework / db logic
  • Queries / Commands - SentinelQueries / SentinelCommands - The "workflows" we'll be running, split by purish and side-effects
  • Presentation - SentinelPresentation - Our server-side UI code (you could also put your APIs here if you wanted)

I've written a lot of guides on how all of this works so I'd encourage you to take a look at the app running locally, the code, and dive into some of these if you want to learn more.

Backend Guides

Frontend Guides

Data Guides

Next

That should get you up and running with a fullstack F# app using CloudSeed. Let me know if you have any questions / suggestions / etc - I'm happy to help.

Want more like this?

The best / easiest way to support my work is by subscribing for future updates and sharing with your network.