Skip to content
Get started
Documentation menu

First run

In this guide you claim your new Hatamoto site in the browser. A wizard of six screens creates your owner account and asks for your site's name, address, language, email, colour and content. At the end you are signed in and your site shows its name.

Before you start

Steps

  1. Find the setup code. The setup code is a one-time code the server prints to its log so only someone with access to the server can create the first owner. Look for a line containing: 
    no users yet: open /admin/setup and enter the setup code K7M2-RT9P

    Where to look:

    • The program file: the terminal where ./hatamoto serve runs.
    • Docker: run docker compose logs hatamoto | grep -i setup in the folder with your docker-compose.yml file, the file that describes your Docker setup.
    • A service managed by systemd, the service manager on most Linux servers: the service log, as shown in Deploy with systemd.

    The code has eight letters and digits in two groups of four. Case and the dash do not matter. A new code is made at each start until the first account exists. If you set HATAMOTO_SETUP_CODE yourself, the log does not print a code: use the value you set.

  2. Open http://localhost:8090/admin, or your server's address followed by /admin. With no accounts, Hatamoto sends you to /admin/setup. A bar at the top shows the six steps: Your account, Your site, Email, Look, Content and Done.
  3. On Your account, enter the setup code, your name, your email address and a password of at least 12 characters, twice. Select Create account.

    This creates your account with the owner role, the set of things an account may do: an owner can do everything. You are signed in at once.

  4. On Your site, fill in the four fields and select Continue. You can change all of them later in Settings.
    FieldWhat to enter
    Site nameShown in the header and in page titles. Up to 120 characters.
    Site addressYour public address, such as https://example.com, with no path. You may leave it empty for now.
    LanguageThe one language of your whole site; see One site, one language. It starts as en.
    Time zoneIt starts as UTC. Pick the zone your site works in.
  5. On Email, enter your mail provider's details so password resets and form notices reach people, and select Save and continue. Hatamoto checks the connection first and saves nothing if it fails. Or select Skip to set email up later at Settings > Email, or to keep using the server's SMTP_* settings; see Set up email.
  6. On Look, pick a Brand colour for the built-in theme and select Continue. It is a six-digit colour code and starts as #0060df.
  7. On Content, choose what your site starts with and select Finish setup:
    • Start empty: keep only the starter home page.
    • Install starter content: adds a sample home page, About and Contact pages, two blog posts, header and footer menus and a contact form. If it stops part way, choose it again: finished items are skipped.
    • Import from WordPress: finishes the setup and opens the WordPress import wizard. See WordPress import.
  8. Done links to your site, your content, user invitations and settings. When email is set up, it also offers Send me a test email.

After Finish setup the wizard is closed for good: /admin/setup and the screens before Done answer "Page not found". If you leave before that, sign in again and open /admin/setup to go back to Your site.

Check it worked

Open http://localhost:8090/: it shows the site name you chose. Open http://localhost:8090/admin: you land in the admin, already signed in.

Your site also serves robots.txt and llms.txt, which tell search engines and AI tools what they may use, and a sitemap, a list of your pages for search engines. On the server, each command prints a short answer:

curl -i http://localhost:8090/health
curl -s http://localhost:8090/robots.txt
curl -s http://localhost:8090/sitemap.xml | head

Links in the sitemap and in emails need your public address: the Site address setting, or PUBLIC_BASE_URL on the server. Reset and invitation emails are sent only when that address and email are both set up.

If something goes wrong:

  • The code is gone from the log. Restart the server to get a new one, or set HATAMOTO_SETUP_CODE and restart.
  • "That code is not right." Use the code from the newest log line: older codes stop working after a restart.
  • "Setup already completed". An account exists. Sign in at /admin/login.
  • You prefer the command line. Run hatamoto user create instead of the first step; see Create users. Then sign in and open /admin/setup to finish.
  • A forgotten password, or a lock. An account locks for 15 minutes after 5 failed sign-ins in a row. On the server, hatamoto user reset-password --email [email protected] sets a new password and unlocks it.

What Hatamoto creates on its first start, and every rule of the setup code, is in Requirements and secrets.

Next steps