Skip to main content

Hands On With Acorn

This walk through guides you on how to use Acorn in your day to day workflow. By the end of this guide, you will be able to deploy and manage Acorns, services, access logs, explore volumes and secrets, and run the app in dev mode. Ensure that you are using the latest version of the Acorn CLI.


This tutorial assumes that the following prerequisites have been completed:

The latest version of the Acorn CLI is installed and configured. For more information about installing or upgrading the Acorn CLI, refer to Installing the Acorn Command Line Interface.

You have logged into the Acorn Dashboard through your GitHub credentials.

Deploying Acorn Apps

We will deploy a simple webapp that interacts with a MariaDB instance to perform CRUD operations.

MariaDB is deployed from an Acorn that creates a service and injects the credentials as secrets into the application. This service is consumed by two Acorn apps – a job which will initialize the database by creating a table and inserting a set of sample records, and the webapp.

Start by cloning the repo and spend a minute to explore the structure.

git clone
cd docs-hands-on-example

The resulting directory structure looks like this:

├── Acornfile
├── app
│   ├── Dockerfile
│   ├── package.json
│   ├── public
│   │   └── index.html
│   └── server.js
└── db-init
├── Dockerfile
├── init.js
└── package.json

The app directory contains the code to expose the UI and API endpoints.

The db-init directory contains the code to initialize the database.

Both the directories have a Dockerfile that will be used to build container images.

The top-level directory has an Acornfile that brings everything together. The Acornfile defines the MariaDB service followed by the run-to-completion job to initialize the database, and finally the webapp. The parameters needed to connect to the database like the host, port, and credentials are injected into the job and the API backend through a set of environment variables.

acorn run -n school
# ...
# school
# ┌─────────────────────────────────────────────────────────────────────────────────────────┐
# └─────────────────────────────────────────────────────────────────────────────────────────┘

Wait for the URL to become available and run the below command to access the API. Replace the URL with the actual URL generated for your app.

Click the link, or open in the browser, to see the UI.

You can now add and remove students from the page.

Exploring the Environment and Application

With the application running, let’s dig into the details.

Running the below command shows Acorn that are deployed and running.

acorn apps
# school.db* 4935ab94ff11 3m30s ago OK
# school bcd59c211a1b e0701dc2b023 3m33s ago <> OK

This shows our running web app along with the MariaDB acorn that is providing the service. If you forget the link, or close your terminal, you can run acorn ps to see the apps and their endpoints.

You can stop the application without terminating it. This retains all the associated resources including the volumes.

acorn stop school

Restart the application and check if the data is available.

acorn start school

Reload the webpage, or run acorn ps to get the endpoint url to open in a browser.

You can also view the individual containers and jobs that are running within the application. Lets view the containers and jobs by running the following commands:

acorn containers
# school sha256:ed496878a1876aea3738620bdc0c1fcbf132b71707713d24dcbc62a2738475f9 running 0 21h ago
# school.db.mariadb-55964dc9f-mm4b2 school.db mariadb:10.11 running 0 21h ago
acorn jobs
# school.dbinit completed 9h ago N/A 9h ago

Here you can see the containers and jobs that make up the school Acorn. Acorn separates the containers and jobs into their own groups. The containers are the long running processes that make up the application. The jobs are run-to-completion tasks that are typically used to perform management tasks. It is important to note though, a job is run in an container and can be used as a container input value to commands with --container flags.

Accessing the Logs, Events, and the Shell

If you want to see what is happening with the application, or you need to troubleshoot, you can access the logs, events, and the shell of an Acorn.

Viewing Logs

When the application is running, you can access the logs from all the containers or individual containers. Let’s access the consolidated logs from the application

acorn logs school

To follow the output, we can add the -f switch.

acorn logs -f school

Now, when you hit the UI in the browser, you can see the access logs scrolling by.

If you want to access the logs of a specific container or a job, you can do so by first getting the container name and then accessing the logs.

Let’s first look at the logs of the job. The job name is dbinit which is a part of the school Acorn.

acorn jobs school
# school.dbinit completed 9h ago N/A 9h ago

From the above, we know the job container name is dbinit. Let’s access the logs of the job.

acorn logs -c dbinit school
# dbinit-m2rm2.dbinit: Database is already up-to-date.
# dbinit-m2rm2.dbinit: Closing the database connection.
# dbinit-m2rm2.dbinit: Database connection closed.

You can explore the containers available within an Acorn app and then access the logs of individual containers.

acorn container school
# school sha256:9fba330fe1b8722e062bd27f8848fea400f6876e646d282fb7ea298165954c57 running 0 14m ago

You can now follow the logs emitted by the app container.

acorn logs -f
# app-99df6d4d6-n6vhj: Server running on <http://localhost:3000>
# app-99df6d4d6-n6vhj: [2023-10-09T05:27:34.437Z] GET /students
# app-99df6d4d6-n6vhj: [2023-10-09T05:37:35.142Z] GET /students

Each HTTP request is written to STDOUT as well as to a file in the logs directory.

Viewing Events

Acorn apps generate events that can be either accessed from the shell or the dashboard.

acorn events app/school
# app/school 8e6e72ba72519e2df4620f4d6449074a AppCreate username 2023-10-17 21:13:43.65855 -0700 MST App acorn/school created
# app/school 10299167e1181aab0496367b31aed7da AppSpecUpdate username 2023-10-17 21:23:27.405748 -0700 MST Acorn definition updated acorn/school
# app/school 30c6918b98181444b824ac7572ccce99 AppSpecUpdate username 2023-10-17 21:25:39.565005 -0700 MST Acorn definition updated acorn/school
# app/school d3b029835e180030a4bd23fbb0aecb31 AppSpecUpdate username 2023-10-17 21:31:08.620699 -0700 MST Acorn definition updated acorn/school
# app/school 954a1549d6180698d2ecdc84c6d47a92 AppSpecUpdate username 2023-10-17 21:35:31.333494 -0700 MST Acorn definition updated acorn/school
# app/school 59a5273e38184da84c2861a98481a0d3 AppSpecUpdate username 2023-10-17 21:37:25.284371 -0700 MST Acorn definition updated acorn/school
# app/school 7ac56f28b618468e189731c385b64a86 AppSpecUpdate username 2023-10-17 21:39:15.413501 -0700 MST Acorn definition updated acorn/school
# app/school cca0ec7154e220e3110cf16f29abc5cc AppSpecUpdate username 2023-10-17 21:47:09.718696 -0700 MST Acorn definition updated acorn/school

The events let you know who did what action and when. This is useful if you aren't sure who deployed the Acorn, or made a recent change.

Shell Access

Let’s access the files written to the filesystem by accessing the shell of the container. We can do this with the below command:

acorn exec school  

Once within the shell, you can see the contents of the file api_logs.txt available under the logs directory.

You can run the commands within the container shell by passing them as parameters

acorn exec school /bin/sh -c 'ls logs/'

Exploring the Volumes and Secrets


As mentioned in the previous steps, the logs directory is a persistent volume attached to the application.

You can list the volumes with the below command:

acorn volumes
# school.log-data log-data 1Gi ebs-retain bound RWO 30m ago
# school.db.db-data db-data 1Gi ebs-retain bound RWO 31m ago

The volume, log-data, is created because we explicitly mentioned it in the Acornfile with the below definition:

volumes: {
"log-data": {}

The db-data volume is created by the MariaDB Acorn Service to persist the data stored in the database.

When we delete an Acorn, the volumes associated with it are retained by default. We will see how to delete the volumes in the cleanup section of this guide.

An Acorn Service is designed to abstract the provisioning of the resources and injecting the credentials into the application consuming the service. Since the credentials and configuration is created dynamically, they can be accessed by the application at runtime without any knowledge.


To explore the secrets generated by our Acorn Service, run the below command:

acorn secret
# school.db.admin basic [password username] 38m ago
# school.db.user basic [password username] 38m ago

Going back to the Acornfile, we injected the admin credentials into the application as environment variables.

containers: school: { 
env: {
"DB_USER": "@{service.db.secrets.user.username}"
"DB_PASS": "@{service.db.secrets. user.password}"
"DB_HOST": "@{service.db.address}"

Let’s reveal the admin credentials and compare them with the environment variables available within the application container. The values in your output will differ because they are randomly generated at runtime. The important thing to note is that the values match.

acorn secret reveal school.db.user
# school.db.user basic password a^+GQpY!2Y+_m&4p
# school.db.user basic username btzgszisyus

Let’s check the environment variables to see if they are the same.

acorn exec school /bin/sh -c 'echo $DB_USER;echo $DB_PASS'
# btzgszisyus
# a^+GQpY!2Y+_m&4p

The variables in the container match the values of the secrets.

Using the Dev Mode to Interactively Debug the App

Acorn aims to be friendly to development and operations. In the day to day workflow, developers need to be able to attach debuggers, access databases, and make changes to the code.

Port Forwarding

It is possible to forward the port of a service locally. We can then access the remote service with local clients which simplifies the debugging process.

Let’s forward the port 3306 of MariaDB service available through school.db Acorn.

acorn port-forward school.db 3306

Assuming you have the MySQL client installed on the development machine, you can reveal the credentials of the root user and access the database instance.

mysql -h -u root  -p

In a different terminal window, reveal the secret and use that with MySQL client.

acorn secrets reveal school.db.admin
# school.db.admin basic password a^+GQpY!2Y+_m&4p
# school.db.admin basic username root

Once you are in the MySQL shell, you can access the database and run SQL commands.

mysql> show databases;
| Database |
| information_schema |
| instance |
| mysql |
| performance_schema |
| sys |
5 rows in set (0.23 sec)

mysql> use instance
Reading table information for completion of table and column names
You can turn off this feature to get a quicker startup with -A
Database changed

mysql> select * from students;
| id | name | age |
| 1 | Alice | 20 |
| 2 | Bob | 22 |
| 3 | Charlie | 21 |
3 rows in set (0.24 sec)

mysql> quit;

Dev Mode

Acorn also provides a dev command that enables you to run your project in a live-reload mode, which automatically reloads your application whenever you make changes to your code.

You can launch an application in dev mode by running acorn dev or acorn run -i command. Every time the Acornfile or Dockerfiles are changed, the application is automatically built and redeployed. The logs are streamed to the console.

It’s also possible to attach a dev session to a pre-existing Acorn. Let’s attach our application to the dev session.

acorn dev -n school

Lets make a small change in the UI code to update the user prompt. Open the file app/public/index.html with your favorite editor and make the following changes.

<!-- Form for entering new student -->
<div class="card">
<div class="card-header">
Enter New Student

Change Enter New Student to Enter New Student Information.

<!-- Form for entering new student -->
<div class="card">
<div class="card-header">
Enter New Student Information

After saving the file, you will notice the file is synchronized to the container running the application and the server process is restarted. Now you can reload the UI and see the changes reflected.

When you are done editing and trying things, you can exit the dev mode by pressing Ctrl+C. You'll notice that the deployment goes back to the previous state, before you started the dev mode.


Now that we have walked through the day to day of interacting with Acorns, the last step is to clean things up.

We can delete the application by running the below command:

acorn rm school

Acorn will say that the application has been deleted. This means the app and containers have been removed along with the school.db app and containers. The volumes and secrets are still retained as a safety precaution against accidental deletion. It should also be noted, the school.db app is removed because it does not contain a job that responds to the delete event. Nested Acorns that have clean up jobs, will not be deleted when the parent is deleted, and must be removed explicitly.

Lets delete the secrets and volumes associated with the application.

First list secrets so we can know their names:

acorn secrets
# school.db.admin basic [password username] 23h ago
# school.db.user basic [password username] 23h ago

Then remove them:

acorn secrets rm school.db.admin school.db.user
# school.db.user
# school.db.admin

Now lets do the same thing for volumes:

acorn volumes
school.log-data log-data 10Gi ebs-retain released RWO 70m ago
school.db.db-data db-data 10Gi ebs-retain released RWO 70m ago

Now we can remove the volumes by name:

acorn volumes rm school.log-data
acorn volumes rm school.db.db-data

We walked through this process manually, but it is possible to delete more aggressively. For example, to delete all of the resources in the school app, we can run:

acorn rm -af school

This command will remove the volumes, secrets, and nested Acorns that do not have a job that responds to the delete event. If your nested Acorn has a job that responds to the delete event, then you will need to remove it explicitly. This is done so that accidental deletion of persistent data is avoided.

Caution should be used when deleting everything like this, there isn't a way to recover the data once it is deleted.

Now that everything is cleaned up, you are ready to work with Acorn in your day to day workflow.