13. Create Your First Volume — studiofs init¶

Work in progress

S3 already has room for your files, PostgreSQL is ready to remember their structure, Tailscale connects them, and StudioFS is installed. Now we will bring these components together in a volume—a separate StudioFS drive with its own name, settings, and encryption key.

That is what studiofs init does. It creates a new volume, but does not yet attach it as a drive in your system. The drive letter or mount directory comes in the next step. We can plan the housewarming, but let us hold off on moving in the furniture.

What needs to be ready¶

Run the command on the computer where you will start working with the volume, under your usual user account. Local metadata is created for that user; running through sudo may leave it in another user's home directory.

You need the S3 API address, a private bucket, a region, and dedicated access keys from chapter 06. You will also need a PostgreSQL DSN—a connection string containing the address, user, and password. The checks in chapter 09 must pass from this particular computer.

Remote PostgreSQL must be reachable through a private route, such as Tailscale or NetBird. Do not expose port 5432 to the entire internet. Installing a VPN alone does not close a public port: check the port binding and the server's firewall rules.

Choose a short, clear name, such as studio-projects. This is the volume name, not the bucket name or its future drive letter. Latin letters, numbers, and hyphens are convenient to start with. Do not enter a path: /, \, and : are forbidden in the name. StudioFS will also use this name in the object prefix: studio-projects/objects/.

The creation command¶

First, you can check the available options in your installed version:

studiofs init --help

Below is a template: replace all uppercase values with your own. The example host names are placeholders, not real services. The command is shown on one line so you can adapt it for Bash, PowerShell, or another shell without different line continuation characters:

studiofs init studio-projects --endpoint 'https://S3_API_HOST:PORT' --bucket 'YOUR_PRIVATE_BUCKET' --region 'YOUR_S3_REGION' --access-key 'YOUR_ACCESS_KEY_ID' --secret-key 'YOUR_SECRET_ACCESS_KEY' --meta 'postgresql://YOUR_PG_USER:YOUR_URL_ENCODED_PASSWORD@PRIVATE_PG_HOST:5432/studiofs?sslmode=require'

In the example, PRIVATE_PG_HOST stands for your server's private hostname.

In a URL, a password containing characters such as @, :, /, or # must be correctly encoded as a URL component. Quotes around the DSN protect the string from the shell, but do not perform that encoding. A password written incorrectly can easily turn into a “strange server address.”

What happens after you run it¶

StudioFS first connects to the PostgreSQL maintenance database postgres and checks whether the studiofs database exists. If it does not, StudioFS tries to create it. The database name is fixed: putting another name in the DSN will not create a separate database for this volume—StudioFS rewrites it to the required name.

Next, the command checks the S3 bucket. If the check fails, it tries to create the bucket. This may require the additional CreateBucket permission. A message about attempting creation does not prove the bucket is missing: incorrect keys, an endpoint, or permissions may have caused the initial failure. A bucket that has already been created and is accessible avoids the need for permission to create it.

After the checks, StudioFS prepares shared metadata, checks whether a volume with that name already exists, and creates the local database, root directory, and encryption key for the new volume. The initial state is published to PostgreSQL.

By default, the local database is at ~/.studiofs/meta/studio-projects/studio-projects.db, where ~ is the user's home directory. If you have configured STUDIOFS_CLIENT_ROOT, that directory will be the root instead. The command shows the exact path at the end.

The settings contain credentials, and PostgreSQL also stores the volume's key material. Do not assume the local database or shared metadata is safe to publish simply because file contents are encrypted.

How to tell whether it worked¶

Wait for the command to finish without an error. At the end, you should see:

✓ Volume 'studio-projects' initialized

Alongside it will be the volume UUID, block size, endpoint and bucket, the label Metadata backend: Postgres, the volume ID, and the path to local metadata. Check that the name and bucket are the ones you intended. A successful PostgreSQL connectivity message alone is not enough: initialization continues after that.

You can also inspect the status:

studiofs status studio-projects

Expect information about your volume, rather than a Volume ... not found message.

If you need to try again¶

init creates a new volume and is not a safe command for “updating settings.” After an error, first read it and establish which step the command reached.

• S3 error: check the endpoint, region, keys, and access to the existing bucket. Do not grant administrator permissions at random just because a message mentions creating it.
• PostgreSQL error: check the private route, password, TLS, and access to both databases—postgres and studiofs. A database creation error may mean an administrator needs to help prepare it in advance.
• The volume already exists in PostgreSQL: do not run destroy, even if the error text suggests it. This is not a routine retry step. If the volume already exists and you need to attach another computer, use studiofs discover, covered in chapter 16.
• The prompt Do you want to CLEAR it and start fresh? [y/N]:: StudioFS has found a local metadata directory and is offering to delete it. Unless you are certain it contains only an unwanted remnant of a failed test, press Enter or type n. Answering y deletes the directory; it does not simply repeat the check.

Do not assume that every failed initialization automatically undoes all preceding actions. A database, bucket, local files, or a volume record may already have been created. If the final message is missing but the name is already taken or a clearing prompt appears, save a redacted copy of the error text and investigate the state before proceeding. Manually deleting metadata or creating another volume over the same prefix is a poor substitute for diagnosis.

Once the command has completed successfully, there is no need to repeat init. The volume is created; in the next chapter, we will attach it to your computer's file system.

Contents · Українська · ← Previous · Next →