How data works 2: Mounts - data in files

Add data

In your local repository, checkout main (git checkout main) and then run the following command:

upsun environment:deactivate updates -y

Viewing the project in the management console, you will only be able to see the updates environment if the inactive Filter has been selected. While the updates branch still exists on the remove, it is now an inactive environment. There is no deployed site there any more.

Create a new environment called data:

git pull upsun main
upsun environment:branch data

Then add the following to the bottom our your .upsun/config.yaml file:

disk: 512
mounts:
    'data':
        source: local
        source_path: data

At runtime, the filesystem your application runs from is read-only. You saw in the previous guide how this rule provides the ability to leverage Git so that Upsun can reuse build images.

Many applications, however, do require write access to parts of the filesystem at runtime. If your users upload files to your site, the directory where you would keep those files is one example.

On Upsun, you must define these kinds of directories explicitly by configuring a mount for your application using the mounts attribute. These directories do not contain committed files, only data. The change above defines a single mount accessible within the filesystem at ~/data, and it has been given 512 MB of disk to work with.

Locally, run the following commands:

mkdir data && echo "First data file." > data/data.txt && echo data >> .gitignore

data is now an uncommitted subdirectory in your repository, containing one data file data.txt.

Commit and push this change:

git commit -am "Add some data." && git push upsun data

Next, upload the new file to the mount you just created on the environment.

upsun mount:upload --mount=data --source=data

Verify that the data has been uploaded to the data environment by running the following:

upsun ssh -e data -q 'cat data/data.txt'
First data file.

Branches

From the local branch data, run the command:

upsun environment:branch data-child

You will now have a project structure that looks like this in the management console.

Now run the command:

upsun ssh -e data-child -q 'cat data/data.txt'

You will see the contents of the previous environment: First data file.. Like before, this child environment (data-child) has inherited infrastructure from its parent (data), but now it also includes it’s data when it was created.

Merges

Now for the opposite direction. In your terminal, still checked out from data, run this command:

upsun environment:merge -y

When the activity has completed, check the mount now available on the production branch:

upsun ssh -e main -q 'cat data/data.txt'

While the mount is now present on the production environment, the file is not. Data is inherited by child environment from their parents, but does not make it upwards via merges. The only way to move up to production is via commits.

Syncing data

SSH into the production environment:

upsun ssh -e main

Within that session, create a new data file in the mount:

echo "PRODUCTION data file." > data/data.txt

Then close the session using ctrl + d. While still on the data branch locally, run the following command:

upsun environment:sync data

Let the activity complete, then run:

upsun ssh -e data -q 'cat data/data.txt'
PRODUCTION data file.

With the above command, you’ve re-synced production data to the child environment, data.

Recap

While data is handled slightly differently than code, on Upsun environments also inherit data from their parent environments by leveraging Git.

• It is possible to define mounts, which retain write access at runtime to contain and revise data in files.
• Branching from a parent environment (production, or otherwise) automatically inherits all of the data within mounts to child environments.
• Data flows down, not up, so production data is secure from modification during merges.
• At any time you can re-sync the data within a child development environment to match production with platform environment:sync.

Inheriting production data is how Upsun provides true staging environments for your work. Production data, inherited infrastructure, and reusable builds keep the whole process consistent and predictable so that you can know for certain that behaviour in staging will match behaviour in production when you merge.

Data in files is not the only data you’ll be interested in, however. Upsun handles production data within services in exactly the same way. Just like mounts, Upsun provides committable configuration for services in a wholly managed way.

So before you see how data is inherited in databases and other services, in the next section you will see how to create services using Upsun's managed services configuration.