205 docs website first draft finishing (#306)

* removes old config

* opens portable links in external window

* adds scaffold for further documentation

* makes edits to getting started

* adds examples and notes on game engine / cloud platform support

* separation between before and after links section

* writes in debugging section

* removes un used flag

* global flags + links to deeper doc pages

* build-templates command docs

* debugging docs

* global flags, flags vs options

* omgd game docs

* infra docs

* adds servers subcommand docs

* sets up core concepts index page

* file structure docs

* profiles docs

* more billing warnings

* adds template docs

* markdown fixes

* your costs, not ours

* periods, game enging

* extraneous

* pushes users to read docs at site

README.md

@@ -20,47 +20,7 @@ For now, you need to grab a [binary from our release page](https://github.com/ne
 
 If you're on Windows, [here's a guide to adding executables to your PATH](https://stackoverflow.com/questions/4822400/register-an-exe-so-you-can-run-it-from-any-command-line-in-windows), and if you're on Mac / Linux, [here's a guide](https://medium.com/codex/adding-executable-program-commands-to-the-path-variable-5e45f1bdf6ce) for you.
 
-### Local Development
-
-#### Prerequisites
-
-For local development only, you'll need `docker` and the `docker compose` plugin. We recommend using [Docker for Desktop](https://www.docker.com/products/docker-desktop/). You don't need a docker account.
-
-#### Local setup
-
-Start by downloading one of the [examples using Godot](https://github.com/orgs/newnoiseworks/repositories?q=example&type=all&language=&sort=) from our repositories.
-
-In the example's folder, run the following commands.
-
-```console
-> omgd build-templates
-> omgd game build
-> omgd servers start
-```
-
-For details on each command and what it does, check the [full documentation](https://newnoiseworks.github.io/omgd).
-
-Check your `game/dist` folder, there should be executables for the built game that you can load. If the `profiles/omgd.yml` file references a "web" servers target, you likely have a web based example built and running on `https://localhost:3030`. Also, try loading the project in your game enging from the `game` folder; buiding and running the game from the engine should work against the spawned server.
-
-##### Check server logs
-
-To see a running log from the servers, use the following command:
-
-```console
-> omgd servers logs
-```
-
-### Cloud Deployment for Testing
-
-#### Prerequisites
-
-For cloud deployment, you'll need to install [Terraform](https://www.terraform.io).
-
-You'll also need a [Google Cloud Platform (GCP)](https://cloud.google.com/gcp) account with billing enabled.
-
-<b>NOTE: OMGD is NOT responsible for your billing or finances on GCP or any cloud provider. You must monitor this. However, we default instances to `f1-micro`, and if you shut down your instances after testing, you shouldn't be paying more than a few pennies to dollars per month, USD.</b>
-
-#### Cloud Setup
+### Getting Started
 
 Please see the [getting started section](https://newnoiseworks.github.io/omgd/pages/getting-started/#deploying-to-the-cloud) for more.
 

cmd/buildTemplates.go

@@ -57,5 +57,4 @@ func init() {
 	// buildTemplatesCmd.Flags().BoolP("toggle", "t", false, "Help message for toggle")
 	buildTemplatesCmd.Flags().StringVar(&templateExtension, "ext", "tmpl", "File extension used for templates. Don't include the period.")
 	buildTemplatesCmd.Flags().BoolVar(&removeTemplateAfterProcessing, "remove", false, "Remove template file after processing")
-	buildTemplatesCmd.Flags().BoolVar(&useLocalProfilesDir, "profiles", false, "uses local .profiles/ dir instead of build .omgd/ dir in main project lib")
 }

cmd/infra.go

@@ -18,11 +18,10 @@ var infraCmd = &cobra.Command{
 	Short: "Deploys and destroys cloud infrastructure",
 	Long: `Deploys and destroys cloud infrastructure
 
-$ omgd infra deploy | Deploys cloud infrastructure via terraform
-$ omgd infra game-deploy | Builds and deploys clients and server to infra
-$ omgd infra destroy | Destroys cloud infrastructure via terraform
 $ omgd infra project-setup | Initial one time project level infra setup
-$ omgd infra project-destroy | Destroy project infra setup - NOTE: This does NOT destroy individual instances, and may leave compute boxes up to be destroyed manually. Use omgd infra destroy for that first.`,
+$ omgd infra project-destroy | Destroy initial project infra setup
+$ omgd infra instance-deploy | Sets up a cloud VM instance of the game servers against a non local profile
+$ omgd infra instance-destroy | Destroys cloud VM created against supplied profile`,
 	Run: func(cmd *cobra.Command, args []string) {
 		profile := utils.GetProfile(ProfilePath)
 		command := args[0]

cmd/servers.go

@@ -22,7 +22,6 @@ var serversCmd = &cobra.Command{
 $ omgd servers start          | starts local docker servers containers
 $ omgd servers stop           | stops local docker servers containers
 $ omgd servers logs           | prints logs from docker containers
-$ omgd servers logs --verbose | tails / follows logs continuously
 $ omgd servers status         | prints status of running docker containers
 $ omgd servers deploy         | deploys servers folder to profile target, not usable with local profile
 	`,

docs/content/_index.md

@@ -1,11 +1,6 @@
 ---
 title: OMGD
 bookToc: false
-# bookFlatSection: false
-# bookHidden: false
-# bookCollapseSection: false
-# bookComments: false
-# bookSearchExclude: false
 ---
 # OMGD
 
@@ -38,9 +33,30 @@ This is how to setup a live game server - dedicated, another set of software, or
 
 OMGD uses Docker and Terraform for you to make everything work.
 
+## Game Engines and Cloud Platforms
+
+OMGD is built to be agnostic to game engines and cloud platforms.
+
+As long as the game engine can build executables via a docker image, and the cloud platform is compatible with Terraform, OMGD should be expandable to support any combination of the two.
+
+As of January 2024, OMGD only supports [Godot game engine](https://godotengine.org) and [Google Cloud Platform (GCP)](https://cloud.google.com/).
+
+{{<hint danger>}}
+OMGD is not responsible for your cloud billing or costs!
+{{</hint>}}
+
 ## Check out some examples
 
+[Godot 4 Dedicated Server Example](https://github.com/newnoiseworks/omgd-godot4-dedicated-example)
+<br />
+[Godot 4 with Nakama 3 Server Example](https://github.com/newnoiseworks/omgd-godot4-nakama3-example)
+<br />
 [Godot 3 Dedicated Server Example](https://github.com/newnoiseworks/omgd-godot3-dedicated-example)
+<br />
+[Godot 3 Dedicated Server and Nakama 3 Server Example](https://github.com/newnoiseworks/omgd-godot3-dedicated-nakama3-example)
+<hr />
+
+[All Examples](https://github.com/orgs/newnoiseworks/repositories?q=omgd+example&type=all&language=&sort=)
 
 ## Try out the latest build
 

docs/content/docs/cli/_index.md

@@ -0,0 +1,24 @@
+---
+title: CLI API
+---
+
+# OMGD CLI API
+
+OMGD is a command line interface based application. Below are the basic commands and their descriptions. Click the command for deeper information and options.
+
+## Command List
+
+| <div style="min-width:200px">Command</div> | Description |
+| -- | -- |
+| [build-templates](/docs/cli/build-templates) | Builds template files using OMGD profile data. |
+| [game](/docs/cli/game) | Builds game projects via docker. |
+| [infra](/docs/cli/infra) | Sets up cloud infrastructure and development instances via terraform and deployment scripts. |
+| [servers](/docs/cli/servers) | Manages docker containers, most useful for local development, limited support for commands against cloud instances if supplied a profile attached to a cloud instance. |
+
+## Global Flags
+
+| <div style="min-width:150px">Option Flag</div> | Default | Description |
+| -- | -- | -- |
+| `-p`, `--profile` | `profiles/local.yml` | The OMGD YML profile to run command against. See [profiles section](/docs/core-concepts/profiles) for more details on profiles. |
+| `--output-dir` | `.` (current working directory) | The directory that OMGD should output files into. Defaults to current directory. |
+| `--help` | Provides help on any `omgd` command. |

docs/content/docs/cli/build-templates.md

@@ -0,0 +1,29 @@
+---
+title: "omgd build-templates"
+---
+
+## `> omgd build-templates`
+
+This will search through your directories for all files ending in `.tmpl`. It will use the profile provided (`profiles/local.yml` by default) to supply data to that file, generating a file which strips the final `.tmpl` from it's name, e.g. `example.gd.tmpl` will create a file `example.gd`.
+
+These files are used to inject IP address and hostname data of newly created servers into the game and server builds so multiple deployments can easily exist and be driven by your YML profile definitions.
+
+See the [templates core concept page](/docs/core-concepts/templates) for more.
+
+## General Form
+
+`omgd build-templates [OPTIONS]`
+
+## Flags
+
+### Extension (`--ext [STRING]`)
+
+By default, the `build-templates` command will search for files with the extension `tmpl`. You can adjust this by supplying your own extension. Do not include the `.` before the extension name, just the letters itself.
+
+E.g. `omgd build-tempaltes --ext customtmpl`
+
+### Remove (`--remove`)
+
+If you pass this flag, the template files will be deleted after generating. Useful in edge cases when using OMGD with other build and deployment systems.
+
+e.g. `omgd build-templates --remove`

docs/content/docs/cli/game.md

@@ -0,0 +1,39 @@
+---
+title: "omgd game"
+---
+
+## `> omgd game`
+
+This command is used for building and managing games in the `game/` folder. It will use the profile provided and the parent `omgd.yml` profile to infer what targets are run.
+
+The targets that are defined in the profiles link to service names in the required `game/docker-compose.yml` file. In the example projects, these default to `build-[OPERATING SYSTEM NAME]`, e.g. `build-windows` for windows executables.
+
+The profile listing for each target can also supply a directory to copy the built game to. This is useful for moving web client builds as well as dedicated server builds into appropriate folders in the `servers/` directories such to run the game as internet accessibly servers. See the [profiles core concept page](/docs/core-concepts/profiles) for more information.
+
+## Subcommands
+
+### `> omgd game build`
+
+Builds the game against the supplied profile, `profiles/local.yml` by default. To build a game against a profile named staging.yml:
+
+```
+omgd game build -p profiles/staging.yml
+```
+
+To build against the default local profile, just run
+
+```
+omgd game build
+```
+
+## Flags
+
+### Targets (`--targets [STRING]`)
+
+Supply targets as named by the `game/docker-compose.yml` services to run game builds against. Can be useful to limit build targets for testing.
+
+```
+omgd build game --targets "build-x11 build-windows build-web"
+```
+
+This will ignore the `omgd.game.targets` section of the compiled profile and attempt to run `docker` commands against the supplied targets which should map to build services as specified in `game/docker-compose.yml`

docs/content/docs/cli/infra.md

@@ -0,0 +1,43 @@
+---
+title: "omgd infra"
+---
+
+## `> omgd infra`
+
+Manages all cloud infrastructure creation for your project via internal Terraform files and deployment scripts.
+
+If you wish to use your own Terraform and deployment approach, you must create your own files and run them manually in your own processes. You can use [`omgd build-templates`](/docs/cli/build-templates) to inject profile data into terraform and deployment related scripts as needed.
+
+{{<hint info>}}
+Commands will copy Terraform and deployment scripts to a hidden `.omgd` folder in your project. At the end of the command's run, unless an error occured, this folder will be deleted.
+{{</hint>}}
+
+## Subcommands
+
+### `> omgd infra project-setup`
+
+This sets up the project on your cloud provider. This will create a data bucket to store terraform config files per each deployment, as well as a VPS network with firewall rules aligned to your port configurations in the profile.
+
+This only needs to be run once against a project. Note that it does NOT set up game servers, it is just to create the resources necessary to do so.
+
+Note that this does not require a profile, and will use the data found in `omgd.yml` as well as `omgd.cloud.yml` for all resource creation.
+
+### `> omgd infra project-destroy`
+
+This will destroy the data bucket and VPS network created in `omgd infra project-setup`.
+
+Note that if this cannot run, you may manually delete the project on your cloud infrastructure, or it's individually created GCS bucket and VPS network which should be named against the `omgd.name` value in your top level `omgd.yml` profile.
+
+### `> omgd infra instance-setup -p [PROFILE]`
+
+e.g. `omgd infra instance-setup -p profiles/staging.yml`
+
+This will setup a VM (virtual machine) on your cloud infrastructure that you can deploy built game servers to. Note that it does NOT deploy the game server, just sets up the cloud infrastructure necessary to deploy them later via [`omgd servers deploy`](/docs/cli/servers).
+
+Note that it requires a non local profile. It will write in the newly created VM instance IP into the `omgd.servers.host` value of the provided profile.
+
+### `> omgd infra instance-destroy -p [PROFILE]`
+
+e.g. `omgd infra instance-destroy -p profiles/staging.yml`
+
+This will destroy any VMs setup via a previously run `instance-setup` command. It should reset any `omgd.servers.host` values to `???` after destroying the VM.

docs/content/docs/cli/servers.md

@@ -0,0 +1,67 @@
+---
+title: "omgd servers"
+---
+
+## `> omgd servers`
+
+Manages docker containers that run all necessary servers to run your game. Essentially runs docker commands against provided profiles and game builds.
+
+{{<hint warning>}}
+With the exception of `deploy`, the subcommands below don't work on remote servers defined in profiles when using OMGD on Windows. If you wish to run them, for now you'll need to ssh into the remote servers yourself. All commands should work on local machines though.
+{{</hint>}}
+
+## Subcommands
+
+### `> omgd servers deploy`
+
+Usable after creating a deployment target via `omgd infra instance-setup -p profiles/your-profile.yml`
+
+Requires a non local profile to be referenced with a valid `omgd.servers.host` value to deploy to. Will copy the entire `servers/` folder as it exists to the remote server - be sure to run `omgd game build -p profiles/your-profile.yml` before hand to make sure it uploads builds matching this profile. It will then start docker containers running each server.
+
+```
+omgd servers deploy -p profiles/your-profile.yml
+```
+
+Works on Windows.
+
+### `> omgd servers start`
+
+Starts docker containers representing your servers. Useful in local development. Usable remotely but the above `deploy` command runs the servers independently on their own. Uses the local profile by default. If a non local profile is supplied, it will try to run the command on a remote server.
+
+```
+omgd servers start
+```
+
+If using a non local profile, this command doesn't work on Windows against remote servers for now.
+
+### `> omgd servers logs`
+
+Shows a running log of statements coming from all docker containers. Requires docker containers to be running. Uses the local profile by default. If a non local profile is supplied, it will try to run the command on a remote server.
+
+```
+omgd servers logs
+```
+
+If using a non local profile, this command doesn't work on Windows against remote servers for now.
+
+### `> omgd servers stop`
+
+Stops docker containers representing your servers. Useful in local development to preserve resources or to restart the server after rebuilding it. Uses the local profile by default. If a non local profile is supplied, it will try to run the comand on a remote server.
+
+```
+omgd servers stop
+```
+
+If using a non local profile, this command doesn't work on Windows against remote servers for now.
+
+See below flag for dropping data volumes w/ `omgd servers stop`
+
+## Flags
+
+### Drop volumes (`omgd servers stop -v`)
+
+Only usable with `omgd servers stop`. If any of your servers are writing data to a shared volume created by your docker containers, this will drop that data volume. Useful for database instances like `PostgreSQL` running via Docker for servers like `Nakama` et al.
+
+```
+omgd servers stop -v
+```