What is Cloudy Pad ?

Cloudy Pad lets you deploy a Cloud gaming server anywhere in the world and play your own games - without requiring a powerful gaming machine or a costly subscription:

Features โœจ

  • Run any application (Steam, Pegasus, Firefox...) thanks to Wolf streaming server
  • Deploy on AWS, Google Cloud, Azure or Paperspace
  • Use Spot instances for up to 90% cheaper instances with some Clouders
  • Play 30 hours per month for ~15$ / month or less
  • Pay by the hour, no subscription required
  • Compatible with Moonlight streaming client

Not familiar with Cloud Gaming ? See What's Cloud Gaming and how is Cloudy Pad useful ?

Getting started

๐Ÿš€ Follow Getting started guide to deploy your Cloudy Pad instance

๐Ÿ’ฐ Understand Cloud provider costs - Cloudy Pad itself is free, but Cloud provider usage is not. Make sure you understand Cloud costs before deploying your instance ๐Ÿ˜‰

Development status ๐Ÿงช

This project is still at an experimental phase. While working and allowing you to play in the Cloud seamlessly, there may be breaking changes in the future. Your feedback, bug reports and contribution will be greatly appreciated !

Cloud Providers

Available Cloud providers:

Potential future Cloud providers - upvote them on their GitHub issues!

What's Cloud Gaming ? How is Cloudy Pad useful ?

This page is aimed at non-technical people or those unfamiliar with Cloud Gaming who wants a better understand of what Cloudy Pad can provide. We'll explain:

  • What's "Cloud gaming" ?
  • What is Moonlight and how is it related to Cloud Gaming ?
  • What is a Cloud provider ?
  • What is Docker and why do we need it ?
  • What is the cloudypad CLI ?

Cloud Gaming is the act of playing play video games directly from a server on the internet. This is called "Cloud Gaming". Our goal is to make Cloudy Pad usable by even non-tech savy users. While we're not there yet, we hope this page will help you have a better understanding.

Cloud Gaming

Cloud gaming lets you play video games without needing a powerful console or computer at home. Think of it like streaming a movie on YouTube or Netflix: you open your browser and play a video. In this situation, the video comes from YouTube's Servers into your computer. The Server does the heavy work of generating images for the video, while you only get the result as a video stream.

To play video games you need lots of physical resources, more than what's required to generate a "simple" video stream like YouTube. That's why dedicated consoles or "gaming" computers are often required for recent games. This includes powerful GPUs (Graphical Processing Units) to generate the video stream for our video game. In a classic setup, your GPU is physically located within your machine.

With Cloud Gaming, GPU power is delegated to a computer somewhere on the internet - in the Cloud - while you get the video game stream as a result.

Hence, you don't need a powerful computer at home anymore, just something capable of handling a video stream and a good internet connection. It lets player enjoy games without requiring a high-end computer and occasional players can enjoy games without huge investment in costly materiel.

How do we get such as Server in the Cloud? See Cloud Provider below.

Moonlight

Moonlight is to Cloud Gaming what your browser (Firefox, Safari, Chrome...) is to YouTube: it allows you to connect to a server to play video game while your browser lets you connect to YouTube to watch videos. You install and run it like any other program !

Moonlight is called a Client which will connect to our Server.

Cloud Provider

A Cloud Provider allow you to rent Servers in the Cloud. Much like you'd rent a car for your holidays for a daily fee, Cloud Providers let you rent Servers for an hourly fee. With Cloud Gaming, we're gonna rent a server in order to play our games.

You may already have heard of Cloud Providers such as AWS, Google Cloud, Microsoft Azure, etc. Cloudy Pad lets you (or will let you) play on these Cloud Providers and others, less known but cheaper, more adapted to our usage.

CLI and console

CLI (short for Command Line Interface) allow you to run commands in a terminal (a small window in which you can type text). That's a basic but very powerful way of running programs, and the primary way to run Cloudy Pad which does not (yet) have a graphical interface like your browser would.

Worry not, cloudypad CLI is easy to use and you'll be guided through usage.

Docker

Docker is a tool required by Cloudy Pad to work. While it may seem strange to rely on yet-another technology do run Cloudy Pad, this allows Cloudy Pad to actually much more simpler to install and use, preventing you to install quite a lot of software and applications.

How does it all fit in ?

Here's the thing: deploying a Cloud Server with everything you need to play video games is... a bit complex, to say the least. This documentation may seem a lot already, but it's only scratching the surface.

That's where Cloudy Pad comes in ! Cloudy Pad lets you:

  • Create a Cloud Server suitable for video games and Cloud Gaming using the Cloud Provider of your choice ๐Ÿช„
  • Configure your Cloud Server and Moonlight with all you need to stream video games โœจ
  • Manage your server lifecycle: create, start/stop, destroy... ๐Ÿค–
  • Avoid the complexity of installing and configuring lots of (even more) complicated software, Cloudy Pad does it for you with Docker ! ๐Ÿš€

Getting started ๐Ÿš€

Cloudy Pad deploys a Cloud gaming gear using a Cloud provider of your choice:

Prerequisites

  • A Cloud provider account, one of:
    • AWS
    • Azure
    • Google Cloud
    • Paperspace
  • Moonlight streaming client
  • Docker
    • Rootless Docker is not supported yet
    • For MacOS, OrbStack is recommended over Docker Desktop

Installation

Install latest version of cloudypad CLI:

curl -fsSL https://raw.githubusercontent.com/PierreBeucher/cloudypad/master/install.sh | sh

For other installation methods, see Installation

Cloud provider setup

You may need to setup a few things on your Cloud provider (eg. API key or SSH key). Checkout per-Clouder setup specifities.

Deploy your instance !

Once ready, create your instance with cloudypad CLI:

cloudypad create
# How shall we name your Cloudy Pad instance? (default: mypad) 
#
# Creating Cloudy Pad instance 'mypad'
#
# [...]
#
# ๐Ÿฅณ Your Cloudy Pad instance is ready !

Cloudy Pad will:

  • Create a new Cloud machine and related configurations automatically (you can also use an existing machine)
  • Install GPU drivers and Wolf gaming server
  • Help your Pair with Moonlight

Play your game

Run Moonlight and connect to your instance. Run Steam, login, install your game and enjoy.

To connect with Steam, either:

  • Type your login and password directly
  • Use Steam smartphone app and scan QR code (run Steam app, log in to your account and click on shield button at the bottom)

Stop your instance after gaming sessions

Once you are done, remember to stop your instance to avoid unnecessary costs ๐Ÿ’ธ

cloudypad stop mypad
# or 
# cloudypad destroy mypad

Problem ?

๐Ÿ˜ฑ Something went wrong? See FAQ and known issues or create an issue

Installation

Requirements for all OS

  • A Cloud provider account, one of:
    • AWS
    • Azure
    • Google Cloud
    • Paperspace
  • Moonlight streaming client
  • Docker
    • Rootless Docker is not supported yet
    • For MacOS, OrbStack is recommended over Docker Desktop

Linux

Install latest version of cloudypad CLI:

curl -fsSL https://raw.githubusercontent.com/PierreBeucher/cloudypad/master/install.sh | sh

MacOS

Install latest version of cloudypad CLI:

curl -fsSL https://raw.githubusercontent.com/PierreBeucher/cloudypad/master/install.sh | sh

OrbStack is recommended over Docker Desktop as it's more compatible for Cloudy Pad usage.

Windows

Running Cloudy Pad on Windows requires WSL to be installed.

Once WSL is installed, run a Linux shell and follow Linux installation steps.

Note: If you are using SSH keys mounted from Windows host, make sure they have proper permissions: chmod 0600 ~/.ssh/<key>

Nix / NixOS

Cloudy Pad is packaged as a Nix Flake, see flake.nix

You can include it in your NixOS config or run directly with nix run:

nix run github:PierreBeucher/cloudypad create
nix run github:PierreBeucher/cloudypad -- --version

cloudypad CLI usage

๐Ÿงช cloudypad CLI interface is still experimental and may change in the future

Available commands:

$ cloudypad --help

Usage: cloudypad [options] [command]

Cloudy Pad CLI to manage your own gaming instance in the Cloud.

Options:
  --verbose, -v               Verbosity level (0: silly, 1: trace, 2: debug, 3: info, 4: warn, 5: error, 6: fatal)
                              Alternatively, use CLOUDYPAD_LOG_LEVEL environment variable.
  -V, --version               output the version number
  -h, --help                  display help for command

Commands:
  create                      Create a new instance, prompting for details. Use `create <provider> for provider-specific creation commands.`
  list [options]              List all instances
  start <name>                Start an instance
  stop <name>                 Stop an instance
  restart <name>              Restart an instance
  get <name>                  Get details of an instance
  provision [options] <name>  Provision an instance (deploy or update Cloud resources)
  configure <name>            Configure an instance (connect to instance and install drivers, packages, etc.)
  destroy <name>              Destroy an instance
  pair <name>                 Pair an instance with Moonlight
  help [command]              display help for command

Create instances

Use cloudypad create. It will prompt for required parameters depending on your Cloud Provider.

cloudypad create 

# Or for a specific provider
cloudy pad create azure
cloudy pad create aws
cloudy pad create gcp # Google
cloudy pad create paperspace

You can also specify all arguments as flags for non-interactive creation, for example:

cloudypad create aws \
  --name $instance_name \
  --private-ssh-key ~/.ssh/id_ed25519 \
  --instance-type g4dn.xlarge \
  --disk-size 100 \
  --public-ip-type static \
  --region eu-central-1 \
  --spot \
  --yes --overwrite-existing

Use cloudypad create <provider> --help for available flags.

Alternatively, see CLI integration tests for available flags

Manage instances

List existing instances:

cloudypad list

Get instance details:

cloudypad get mypad

Start/stop/restart instance:

cloudypad start mypad
cloudypad stop mypad
cloudypad restart mypad

Destroy instance:

cloudypad destroy mypad

Instance deployment lifecycle

When you create your instance, creation process goes through various steps:

  • Provisioning: create all Cloud resources for your instance (virtual machine, IP address, virtual disk...)
  • Configuration: install required packages and softwares on your instance (eg. Wolf server)
  • Pairing: pair your instance with Moonlight

These actions can be performed directly via commands below.

Provision an instance to create/update Cloud resources for your instance.

cloudypad provision mypad

Run instance configuration:

cloudypad configure mypad

Pair Moonlight with an existing instance:

cloudypad pair mypad

Connect via SSH to instance

You specified an SSH key when creating your instance. Retrieve your instance details to show its IP and SSH user:

$ cloudypad get mypad
{
  "name": "mypad",
  "host": "5.120.23.178", <==== Instance IP
  "ssh": {
    "privateKeyPath": "/home/crafteo/.ssh/id_ed25519",
    "user": "ubuntu"  <===== SSH user
  },
  "status": {
    ...
  },
  "provider": {
    "aws": {
      ...
    }
  },
}

Connect via SSH:

ssh ubuntu@5.120.23.178

# If needed, specify SSH key
ssh -i /home/crafteo/.ssh/id_ed25519 ubuntu@5.120.23.178

FAQ

General recommendations:

  • Choose a location or region as close as possible to you to avoid too much latency (eg. if you live in the US don't create your instance in Europe)
  • Just provision what you need for: don't create a 500 GB disk if you intend to play a game that will only use 100 GB.
  • GPU / machine type depends on the game you play. See below for recommendations.

AWS

xlarge instances should be enough for most usage. For instance, g4dn.xlarge can run Baldur's Gate 3 in Ultra with 60 FPS 1080 without issues. Use a larger instance only if you have latency related to resource consumption.

Paperspace

Paperspace RTX4000 or P4000 or M4000 are relatively cheap and powerful enough for most use. A P4000 can run Baldur's Gate 3 in Ultra with 60 FPS 1080 without issues.

Use higher-tier instance if you have latency related to resource consumption.

Azure

Use NC or NV instances with 4 to 8 CPUs, eg. one of:

  • NC4as T4 v3 (4 CPU, 28 GB RAM)
  • NC8as T4 v3 (8 CPU, 56 GB RAM)
  • NV6ads A10 v5 (6 CPU, 55GB RAM)

Azure provide more opwerful instance but they are likely too expansive (providing lots of memory and ephemeral storage which is likely unused for gaming but expensive).

Azure gaming instances NG are not yet supported (they use AMD GPU while only NVIDIA is supported for now)

Google Cloud

Use N1 Standard instances with 4 to 16 CPUs with T4 or P4 GPUs. They are the cheapest while providing a good experience, eg. a P4 with 15GB RAM and 8 CPU can run Baldur's Gate 3 in Ultra with 60 FPS.

How can I log-in to Steam?

When you run Steam, you'll be prompted to login either via QR code or login/password. You can either:

  • Enter your login / password manually
  • Use the Steam app to login via QR code: download and login with the Steam app on your smartphone, then click on the Steam Guard icon (shield icon at the bottom) and scan the QR code shown.

How to play game on Steam / Why does my Steam game doesn't launch ?

In order to play games on Steam you may need to enable Proton:

  • Go to game properties (Gear button on the right > Properties)
  • Enable Proton in the Compatibility menu

It's recommended to check your game Proton compatibility on ProtonDB. You may need to add a few Launch options (Game properties > General > Launch options).

Using Steam, why does my game take forever to "cache Vulkan shader" ?

If this is the first time you run your game this is (unfortunately) expected. Steam may cache Vulkan shaders to optimize in-game performance. It should be faster on subsequent runs, if not instantaneous.

I have a black screen when I connect to my instance

If this is the first time you connect to your instance, it may take a few minutes to setup the required components. If after 5 min the problem persists, please file an issue.

I Found an bug or I have a suggestion

If you found a bug or have a suggestion, please report an issue. Thanks for your feedback !

How does all of this work?

cloudypad is a wrapper around a few technologies:

  • Wolf gaming server
  • Clouder-specific tools and APIs to deploy and manage Cloud machines
  • When possible, Pulumi to deploy Cloud machines and resources
  • Ansible to configure machines (drivers, gaming server, etc.)
  • ๐Ÿง  Brain juice from me and other awesome open-source community members

Will Cloudy Pad become a paid product ?

Probably not in its current form. Considering I'm really not happy about the enshittification of the internet, Cloudy Pad will remain FOSS - at least for personal use.

Cloudy Pad may have a Premium or Pro offer in the future, but for a personal simple use it will remain FOSS.

Known issues

Docker for MacOS and VirtioFS

For MacOS, if your Docker installation use VirtioFS, Cloudy Pad may fail with a Docker-related error such as:

Error response from daemon: error while creating mount source path '/private/tmp/com.apple.launchd.ABCDEF/Listeners': mkdir /private/tmp/com.apple.launchd.ABCDEF/Listeners: operation not supported

This is a bug when using Docker for Mac VirtioFS file sharing with SSH agent. The bug is still being worked on, as a workaround you can either:

  • Disable SSH agent before running Cloudy Pad, eg. unset SSH_AUTH_SOCK
  • Switch Docker for Mac config to non-VirtioFS (eg. gRPC FUSE): go to config > Resources > File Sharing and update config.

How much will I pay ? ๐Ÿซฐ

Cloudy-Pad is free and open-source; however, charges may apply when using a Cloud provider. Typically billed resources:

  • Machine usage (GPU, CPU, RAM)
  • Disk storage
  • IP address reservation

Cost estimation

Estimations for a setup with 8 CPUs, ~30GB RAM, 100GB Disk for 30 hours / month:

  • Google Cloud: ~$15.68 (n1-standard-8 with NVIDIA T4000)
  • AWS: ~$15.67 (g4dn.2xlarge with NVIDIA T4000)
  • Azure: ~$11.06 (NC8as T4 v3 with NVIDIA T4000)
  • Paperspace: ~$22.30 (NVIDIA P4000, a bit more powerful than T4000)

See per cloud providers estimations:

Cost optimization

Some general recommandations to avoid unnecessary costs

Spot instances

๐Ÿ’ธ It's recommenced to use Spot instances as they are 30% to 90% cheaper ! As Spot instances interrupton is generally low, you probably won't get interruped during your session. However, make sure to save often nonetheless ๐Ÿ˜‰

Spot instances are supported for Cloud providers:

  • AWS
  • Azure
  • Google Cloud

Paperspace doesn't support Spot instances.

Spot instance usage is specified during instance creation with cloudypad create - you'llbe prompted for Spot instance usage, or you can use flag cloudypad create <provider> --spot for providers supporting Spot instances.

To have a better understand about spot instances, see this article.

Instance setup and specs recommandations

  • Choose a location or region as close as possible to you to avoid too much latency (eg. if you live in the US don't create your instance in Europe)
  • Just provision what you need for: don't create a 500 GB disk if you intend to play a game that will only use 100 GB.
  • GPU / machine type depends on the game you play. Some game will run fine with 4 CPUs but needs high amount of memory such as 32 GB and more, while other will run fine with 4 GB memory but require lots of CPU or a stronger GPU. Refer to requirements and recommended settings for your game.

Turn off your instance while not in use

That goes without saying, remember to turn off your instance while you're not using it to avoid unnecessary costs:

cloudypad stop mypad

AWS monthly cost estimations

Cloudy-Pad is free and open-source; however, charges may apply when using a Cloud provider. Typically billed resources:

  • Machine usage (GPU, CPU, RAM)
  • Disk storage
  • IP address reservation

๐Ÿ’ธ It's recommenced to use Spot instances as they are 30% to 90% cheaper ! As Spot instances interrupton is generally low, you probably won't get interruped during your session. However, make sure to save often nonetheless ๐Ÿ˜‰

Example: using a g4dn.xlarge (16 GB RAM, 4 CPUs, NVIDIA T4) Spot instance for 10 hours / month would cost approximatively 9.63$ / month.

Instance typeRAM (GB)CPUsGPUSpot ?Disk sizeInstance $ / hh / monthCompute $ / monthDisk / month $Total $ / month
g4dn.xlarge164NVIDIA T4Yes100$0.16310$1.63$8.00$9.63
g4dn.2xlarge328NVIDIA T4Yes100$0.25630$7.67$8.00$15.67
g5.2xlarge328NVIDIA A10GYes250$0.41230$12.36$20.00$32.36
g6.2xlarge328NVIDIA L4Yes250$0.39130$11.73$20.00$31.73
g4dn.xlarge164NVIDIA T4No100$0.52610$5.26$8.00$13.26
g4dn.2xlarge328NVIDIA T4No100$0.75230$22.56$8.00$30.56
g5.2xlarge328NVIDIA A10GNo250$1.21230$36.36$20.00$56.36
g6.2xlarge328NVIDIA L4No250$0.97830$29.33$20.00$49.33

*Estimations based on AWS eu-east-1 pricing as of September 2024. Exact prices may vary over time and by region.

Azure monthly cost estimations

Cloudy-Pad is free and open-source; however, charges may apply when using a Cloud provider. Typically billed resources:

  • Machine usage (GPU, CPU, RAM)
  • Disk storage
  • IP address reservation

๐Ÿ’ธ It's recommenced to use Spot instances as they are 30% to 90% cheaper ! As Spot instances interrupton is generally low, you probably won't get interruped during your session. However, make sure to save often nonetheless ๐Ÿ˜‰

Example: using an NV6ads A10 v5 (35 GB RAM, 6 CPUs, 1/6 NVIDIA A10) Spot instance with 100 GB disk for 10 hours / month would cost approximatively 9.24$ / month.

Instance typeRAM (GB)CPUsGPUSpot ?Disk sizeInstance $ / hh / monthCompute $ / monthDisk / month $Total $ / month
NV6ads A10 v55561/6 NVIDIA A10Yes100$0.11410$1.14$8.10$9.24
NC8as T4 v3568NVIDIA T4Yes100$0.09930$2.96$8.10$11.06
NC16as T4 v311016NVIDIA T4Yes250$0.15830$4.73$20.25$24.98
NV6ads A10 v55561/6 NVIDIA A10No100$0.45430$13.62$8.10$21.72
NC8as T4 v3568NVIDIA T4No100$0.75230$22.56$8.10$30.66
NC16as T4 v311016NVIDIA T4No250$1.20030$36.00$20.25$56.25

*Estimations based on Azure US pricing as of September 2024. Exact prices may vary over time and by region.

Google Cloud monthly cost estimations

Cloudy-Pad is free and open-source; however, charges may apply when using a Cloud provider. Typically billed resources:

  • Machine usage (GPU, CPU, RAM)
  • Disk storage
  • IP address reservation

๐Ÿ’ธ It's recommenced to use Spot instances as they are 30% to 90% cheaper ! As Spot instances interrupton is generally low, you probably won't get interruped during your session. However, make sure to save often nonetheless ๐Ÿ˜‰

Example: using a n1-standard-4 (15 GB RAM, 4 CPUs, NVIDIA T4) Spot instance with 100 GB disk for 10 hours / month would cost approximatively 11.54$ / month.

Instance typeRAM (GB)CPUsGPUSpot ?Disk sizeInstance $ / hGPU $ / hh / monthCompute $ / monthDisk $ / monthTotal $ / month
n1-standard-4154NVIDIA T4Yes100$0.0350.11910$1.54$10.00$11.54
n1-standard-8308NVIDIA T4Yes100$0.0700.11930$5.68$10.00$15.68
n1-standard-8308NVIDIA T4Yes250$0.0700.11930$5.68$25.00$30.68
n1-standard-8308NVIDIA P4Yes100$0.0700.24030$9.31$10.00$19.31
n1-standard-8308NVIDIA P4Yes250$0.0700.24030$9.31$25.00$34.31
n1-standard-4154NVIDIA T4No100$0.2200.35010$5.70$10.00$15.70
n1-standard-8308NVIDIA T4No100$0.4400.35030$23.70$10.00$33.70
n1-standard-8308NVIDIA T4No250$0.4400.35030$23.70$25.00$48.70
n1-standard-8308NVIDIA P4No100$0.4400.60030$31.20$10.00$41.20
n1-standard-8308NVIDIA P4No250$0.4400.60030$31.20$25.00$56.20

Instances used for estimation: N1 Standard. Estimations based on Google Cloud us-central-1 as of September 2024. Exact prices may vary over time and by region.

Paperspace monthly cost estimations

Cloudy-Pad is free and open-source; however, charges may apply when using a Cloud provider. Typically billed resources:

  • Machine usage (GPU, CPU, RAM)
  • Disk storage

Example: Using a P4000 with 30 GB RAM, 8 CPU and 100 GB disk for 10 h / month will cost approximatively 12.10$.

Instance typeRAM (GB)CPUsDisk size (GB)Instance $ / hh / monthDisk / month $Total $ / month
P4000308100$0.51010$7.00$12.10
P4000308100$0.51030$7.00$22.30
RTX4000308100$0.56030$7.00$23.80
P5000308250$0.78030$10.00$33.40
RTX5000308250$0.82030$10.00$34.60

*Estimations based on Paperspace pricing as of September 2024. Exact prices may vary over time and by region.

Cloud provider setup

Cloud provider accounts may require some setup before you can your deploy Cloudy Pad instance.

Typical needs:

  • Create your Cloud provider account - If not already done, you'll need to create an account on the Cloud provider you want to use.
  • Configure your Cloud provider credentials - they are required by Cloudy Pad to create your instance.
  • Define Quotas allowing you to deploy GPU - Most Cloud providers require a "quota increase" before allowing you to deploy GPU instances suitable for Cloud gaming.
  • Profile verification - for new accounts, some Cloud provider may require some kind of verification.

Note: future version of Cloudy Pad will automate away most of this setup for you.

See detailed setup per Cloud provider:

AWS account setup

If you don't already have an AWS account, create an account or use an existing account.

Configure your credentials locally (see official documentation)

Check your configuration:

$ aws sts get-caller-identity
{
    "UserId": "AID...YOUR_USER_ID",
    "Account": "123456789",
    "Arn": "arn:aws:iam::123456789:user/crafteo"
}

You're good to go ! Create your instance with

cloudypad create

Quotas

You may need to increase quota to create the related instance type. If you get an error related to quota:

  • Go to AWS console and open "Service Quotas" service
  • Go to AWS Services > search for Amazon Elastic Compute Cloud (Amazon EC2) and open it
  • Search for Running On-Demand G and VT instances (or the related instance type) and request a quota increase
  • Use a quota value according to the instance type you want to use. For example, 2xlarge requires at least 8 vCPU.

See AWS service quotas for details.

Azure account setup

If you don't already have an Azure account, create an account or use an existing account.

Configure your credentials locally (see official documentation)

Check your configuration:

$ az account list
[
  {
    "cloudName": "AzureCloud",
    "homeTenantId": "xxx",
    "id": "xxx",
    "isDefault": true,
    "managedByTenants": [],
    "name": "My Azure Subcription",
    "state": "Enabled",
    "tenantId": "xxx",
    "user": {
      "name": "you@example.com",
      "type": "user"
    }
  }
]

Quotas

You may need to increase quota to create the desired instance type. If you get an error related to quota:

  • Go to Azure console and open "Quotas" service
  • Go to Compute > filter for your Subscription / Location and search for NC, NC or the instance type prefix you want to use
  • Click on quota name and New Quota Request
  • Fill-out the quota request and submit

Quota is usually accepted within 24 to 48h.

Google Cloud

If you don't already have a Google Cloud account, create an account or use an existing account.

Configure your credentials locally (see official documentation)

Check your configuration:

$ gcloud auth list

Credentialed Accounts
ACTIVE  ACCOUNT
*       your_email@gmail.com

Quotas

You may need to increase quota to create the desired instance type. If you get an error related to quota, see Google Cloud Quota doc to update your quotas.

Google Cloud account setup

If you don't already have a Google Cloud account, create an account or use an existing account.

Configure your credentials locally (see official documentation)

Check your configuration:

$ gcloud auth list

Credentialed Accounts
ACTIVE  ACCOUNT
*       your_email@gmail.com

Quotas

You may need to increase quota to create the desired instance type. If you get an error related to quota, see Google Cloud Quota doc to update your quotas.

Paperspace account setup

If you don't already have a Paperspace account, create an account.

If you haven't already setup an SSH key in your profile:

  • If needed, generate an SSH key with ssh-keygen -t ed25519 -a 100
  • Log into your account and go to Your account > SSH Keys > Add new SSH key to add your key. (see doc for details)

You'll need an API key to create your instance:

You're good to go ! Create your instance with

cloudypad create

Development guide

Release

Set export GITHUB_TOKEN=xxx variable and run:

# Will prompt for details and describe required actions
task release-create

Tests

Unit tests

Can be run without prior setup:

task test-unit

Integration tests

Integration tests are manual for now:

  • They require real Cloud accounts
  • They create real Cloud resources which are billed and may persist in case of failure, requiring manual cleanup and knowing about underlying tools

Do NOT run these integration tests if you're not sure about what you're doing to avoid being billed for Cloud resources.

Integration tests using CLI

test/integ/create-and-destroy.sh

Using Mocha

npx mocha test/integ/pulumi/preview.spec.ts
npx mocha test/integ/pulumi/up.spec.ts
npx mocha test/integ/paperspace/client.spec.ts

Development

Development can be done under Nix development shell:

nix develop

Run app directly with npx:

npx tsx src/index.ts configure test-create-destroy-gcp

To debug Ansible playbook easily:

  • Run cloudypad with verbose log to show Ansible inventory temporary file, eg:
npx tsx src/index.ts configure test-create-destroy-gcp -v 4
# ...
# 2024-11-07 10:06:53.036 DEBUG   /dist/src/tools/ansible.js:14   AnsibleClient   Ansible command: ansible-playbook ["-i","/tmp/cloudypad-KlRsDX/inventory.yml","/cloudypad/dist/ansible/playbook.yml"]
# ...

Then run Ansible directly:

ansible-playbook -i /tmp/nix-shell.fD63LM/cloudypad-BX2kYb/inventory.yml ansible/playbook.yml -t wolf --start-at-task="Copy docker-compose file"

Will eventually add an easier way to pass custom Ansible options such as --ansible-additional-flag option or environment variable.

Scripts

Adding a new provider

This section outlines how to add a new provider. It's still scarce but provides a basic entrypoint to help implemented a new provider.

Implement all provider objects:

  • Initializer
  • Provisioner
  • Runner
  • State

Along with clients and others as required.

Add new provider to Manager:

  • CLOUDYPAD_PROVIDER_XXX in src/core/const.ts
  • promptInstanceInitializer prompt
  • getCurrentProviderName
  • getInstanceRunner
  • getInstanceProvisioner

Finalize:

  • Add create PROVIDER command in src/index.ts
  • Add proper bind mounts and environment variables in cloudypad.sh
  • Add test case in test/integ/created-and-destroy.sh

License

Cloudy Pad is licensed under GNU General Public License v3.0