ambient-template

README

Sample App using Ambient

Thanks for visiting! All docs are available here.

This repository contains a sample app to demonstrate how to use the Ambient pluggable web framework. Ambient is a framework in Go for building web apps using plugins. You can use the plugins already included to stand up a blog just like the Bear Blog or create your own plugins to build your own web app. Plugins can be enabled/disabled while the app is running which means routes as well as middleware can also modified without restarting the app. Plugins must be granted permissions above being enabled which provides you with better control over your web app. You can read why the Ambient framework was created here.

Use the Deployment Guide to deploy serverless on Google Cloud (Cloud Run), AWS (App Runner), or Azure (Functions).

Use the Plugin Development Guide to build your own plugins.

Quickstart on Local

To test out the sample web app, you can run these commands below. You can also view screenshots of the app here.

# Build the Ambient interactive CLI (amb) in the current folder.
bash -c "$(curl -fsSL https://raw.githubusercontent.com/ambientkit/amb/main/bash/install.sh)"

# Run the app.
./amb

# Clone the ambient template by typing this command and pressing Enter.
createapp

# Exit by typing `exit` or pressing Ctrl+D.
exit

# Change to the new project folder.
cd ambapp

# Download Go dependencies, create storage files, create .env file, generate a
# new private key, and generate a hash for the password.
# Ensure you replace 'passwordhere' with your passowrd.
make init passwordhere

# Start the webserver on port 8080 (local development with no Docker).
make start

The login page is located at: http://localhost:8080/login/admin.

To login, you'll need:

• the default username is: admin
• the password from above

Once you are logged in, you should see a new menu option call Plugins. From this screen, you'll be able to use the Plugin Manager to make changes to state, permissions, and settings for all plugins.

Container Deployment

To test out the sample app in Docker, you can run these commands:

# Build the Docker container.
make build

# Test running the Docker container.
make run

The login page is located at: http://localhost:8080/login/admin.

Automatic Rebuilds

If you would like to make changes to the code that rebuilds automatically, it's recommended to use air to help streamline your workflow.

# Install air to project bin folder.
make air-install

# Start air to monitor code changes. The web app should be available at:
# http://localhost:8080
make air

Swagger Generation

You can easily generate a Swagger spec for the API from annotations in the code:

# Install Swagger to project bin folder.
make swagger-install

# Generate Swagger spec: swagger.json.
make swagger

# Serve the Swagger spec and open a browser window to view and make requests.
# You need to enable the `healthcheck` and `cors` plugins for this testable UI
# to function properly. You will also need the app running.
make swagger-serve

You can also generate SDKs and a CLI to interact with the API. You can read more about it here.

Environment Variables

You can read about environment variables here.

App Settings

In the main.go file, you can modify your log level with SetLogLevel():

ambientApp, err := ambientapp.NewApp(...)
ambientApp.SetLogLevel(ambient.LogLevelDebug)
ambientApp.SetLogLevel(ambient.LogLevelInfo)
ambientApp.SetLogLevel(ambient.LogLevelError)
ambientApp.SetLogLevel(ambient.LogLevelFatal)

You can enable span tags around HTML elements to determine which content is loaded from which plugins with SetDebugTemplates():

ambientApp, err := ambientapp.NewApp(...)
ambientApp.SetDebugTemplates(true)

You can disable template escaping with SetEscapeTemplates():

ambientApp, err := ambientapp.NewApp(...)
ambientApp.SetEscapeTemplates(false)