Contribute and check out our resources!
Join us on Discord
Website
Features
Documentation
Pricing
Blog
This is a simple demo project meant to introduce you to working with Javascript runtimes on Upsun.
-
Visit the Upsun website to register for a trial account. Complete the information and finish sign up.
-
Create your first organization where the project will live.
-
Choose the Deploy an existing local Git repository option.
-
Name the project, and provide a region for it to be deployed. Keep the Production environment name as the default
main
. Consider selecting a Green region (indicated with a green leaf) where carbon impact is lowest. -
Follow the instructions on the resulting screen to:
-
Clone this repository
git clone [email protected]:upsun/demo-nix-js.git && cd demo-nix-js
-
Connect your local project to Upsun
upsun project:set-remote GENERATED_PROJECT_ID
-
Since Upsun configuration has already been committed to the repo, push to Upsun using the CLI:
upsun push
When the activity has completed, you will be able to visit the deployed project from its generated URL, which you can find with the command
upsun url
This project leverages the Upsun composable image application container syntax, which is built on Nix and Nixpkgs under the hood.
It is organized as to use Turborepo, a high-performance build system that simplifies (for this project) local development.
.
├── .git
├── .gitignore
├── .upsun
│ └── config.yaml
├── apps
│ ├── bun
│ │ └── ...
│ ├── deno
│ │ └── ...
│ ├── main
│ │ └── ...
│ └── nodejs
│ └── ...
├── utils
│ └── ...
├── LICENSE.md
├── README.md
├── package-lock.json
├── package.json
├── shell.nix
└── turbo.json
It is comprised of four application containers :
-
bun
:- a simple bun-based application, deployed with the
bun
Nix package. - configuration to deploy this app can be found under the
applications.bun_app
key in.upsun/config.yaml
.
- a simple bun-based application, deployed with the
-
deno
:- a simple deno-based application, deployed with the
deno
Nix package. - configuration to deploy this app can be found under the
applications.deno_app
key in.upsun/config.yaml
.
- a simple deno-based application, deployed with the
-
nodejs
:- a simple Node.js-based application, deployed with the
nodejs
Nix package. - configuration to deploy this app can be found under the
applications.nodejs_app
key in.upsun/config.yaml
.
- a simple Node.js-based application, deployed with the
-
main
:- a basic Astro applications, deployed with the
nodejs
Nix package. - configuration to deploy this app can be found under the
applications.main_app
key in.upsun/config.yaml
.
- a basic Astro applications, deployed with the
Each of these applications' configuration can be found in the shared .upsun/config.yaml
file.
When deployed to the Upsun management console they will appear like this:
Upsun automatically configures default resources for each application on the production environment (Main), which you can view with the CLI command upsun resources:set
:
$ upsun resources:set
Resource configuration for the project YOUR_PROJECT_NAME (PROJECT_ID), environment main (type: production):
+----------------+------+-----+-------------+-----------+-----------+
| App or service | Size | CPU | Memory (MB) | Disk (MB) | Instances |
+----------------+------+-----+-------------+-----------+-----------+
| bun_app | 0.5 | 0.5 | 224 | | 1 |
| deno_app | 0.5 | 0.5 | 224 | | 1 |
| main_app | 0.5 | 0.5 | 224 | | 1 |
| nodejs_app | 0.5 | 0.5 | 224 | | 1 |
+----------------+------+-----+-------------+-----------+-----------+
You can reuse this same command to reduce the resources of each application to their minimum sizes:
$ upsun resources:set --size '*:0.1' --disk 'database:256' --disk '*_app:0'
...
Summary of changes:
App: bun_app
CPU: decreasing from 0.5 to 0.1
Memory: decreasing from 224 MB to 64 MB
App: deno_app
CPU: decreasing from 0.5 to 0.1
Memory: decreasing from 224 MB to 64 MB
App: main_app
CPU: decreasing from 0.5 to 0.1
Memory: decreasing from 224 MB to 64 MB
App: nodejs_app
CPU: decreasing from 0.5 to 0.1
Memory: decreasing from 224 MB to 64 MB
Service: database
CPU: decreasing from 0.5 to 0.1
Memory: decreasing from 1408 MB to 448 MB
Disk: decreasing from 512 MB to 256 MB
Are you sure you want to continue? [Y/n] Y
You can also increase the number of instances of any application when desired:
$ upsun resources:set --count 'main_app:2' --disk 'database:256' --disk '*_app:0'
...
Summary of changes:
App: main_app
Instance count: increasing from 1 to 2
Note
While the resource allocation activity executes on your production environment, view its log by clicking the three vertical dots on the far right side of the component. Notice as that activity runs, that each of the applications is not rebuilt (the Reusing existing build... text below).
Configuring resources
Updating 'main_app' resources from 0.5 CPU, 224MB RAM to 0.1 CPU, 64MB RAM.
Updating 'bun_app' resources from 0.5 CPU, 224MB RAM to 0.1 CPU, 64MB RAM.
Updating 'nodejs_app' resources from 0.5 CPU, 224MB RAM to 0.1 CPU, 64MB RAM.
Updating 'deno_app' resources from 0.5 CPU, 224MB RAM to 0.1 CPU, 64MB RAM.
Building application 'main_app' (runtime type: generic:2023.1, tree: db728ad)
Reusing existing build for this tree ID
Building application 'bun_app' (runtime type: generic:2023.1, tree: 37066a9)
Reusing existing build for this tree ID
Building application 'nodejs_app' (runtime type: generic:2023.1, tree: e6f7918)
Reusing existing build for this tree ID
Building application 'deno_app' (runtime type: generic:2023.1, tree: 750397e)
Reusing existing build for this tree ID
...
Above all else, this is the principal feature of Upsun.
The configuration file .upsun/config.yaml
enables DevOps workflows and infrastructure-as-code,
but it is this - reusable build images that are environment-independent - that allow you to
provision truly identical preview environments at all will to test your revisions.
See how in the next section.
In the Upsun console, you can view resource consumption over time for each of the containers in the environment's cluster to determine how best resources should be adjusted.
This demo includes two methods for local development.
Both methods require that you have the Upsun CLI installed, and they assume you have already followed the above steps to deploy the project on Upsun.
Requirements:
Run:
- Build the apps:
./utils/local.sh
- Run the local servers:
npm run start
This project leverages the Upsun composable image application container syntax, which is built on Nix and Nixpkgs under the hood.
We can use Nix to replicate the production environment locally, downloading each runtime in isolation instead of doing so manually as is shown above.
Requirements:
Run:
- Build the apps:
nix-shell
Note
The first time you run this command will take some time, but only on that first time.
- Cleanup when finished:
Exit the Nix shell (Ctrl + C, then Ctrl + D), then run:
nix-collect-garbage
In your local environment, run the command:
upsun environment:branch new-feature main
Follow the prompts.
This will create a new environment - which is an exact clone of production, including its data (see the Node.js path (/nodejs
)) to verify this.
Feel free to use the local development instructions to make a revision, push to Upsun (upsun push
), and test in the isolated space using production data.
When you're satisfied, feel free to upsun merge
to promote your revisions into production.
Ultimately, this is the workflow that makes Upsun standout amongst other providers. While you may favor an integration to GitHub or GitLab over this local example, being able to iteratively improve your applications with true staging environments in this way brings you a lot of power.
You currently have a workflow where revisions made locally are pushed directly to an Upsun project. That is, an Upsun project is the primary remote for your development work.
It's more likely that you'll want to integrate the project with a repository on a service like GitHub, building on top of an existing CI/CD workflow.
See the documentation for more details.
If you're looking to understand even more about the Upsun development workflow, follow the steps to spin up the Upsun Demo Project.
There are far more concepts than could be explored in a single demo project, talk, or blog post. But we have some of the best minds in web development and computing ready and excited to help with your side project, experiment, or next big idea.