Build an User Management Application
Introduction & Quick Start Guide
In this tutorial, you will learn how to build a simple user management application using the platformOS User Module. The goal is to understand how authentication works on platformOS, explore the built-in pages provided by the module, and prepare your project for future features such as roles, profile updates, and two-factor authentication.
We will begin with a clean instance, install the User Module, apply Common Styling, and create a minimal homepage.
In the next chapters, we will extend this foundation step by step to add navigation, login/logout, and user-aware layouts.
Tip
You can browse the source code of the User Module in the pos-module-user repository to see every page and helper it provides.
Before we explore the User Module in detail, follow the steps below to set up your environment and prepare a clean project.
Step 1: Create a new instance
Sign in to the Partner Portal and create a new instance:
Example instance name:
user-module-test-00
For more details, refer to the Create an instance guide.
Step 2: Create your project folder
Create the directory for your project and initialize an empty platformOS project:
mkdir user-module-test-00
cd user-module-test-00
pos-cli init
This folder will become your project root.
Step 3: Add and authenticate your environment
Connect your local project to your new instance:
pos-cli env add --url https://user-module-test-00.staging.oregon.platform-os.com staging
A browser window will open prompting you to authorize the connection. For further explanation, see Authenticate your environment.
Step 4: Deploy the empty project
Upload the base project to your instance:
pos-cli deploy staging
Step 5: Install the User Module
Next, install and download the User Module:
pos-cli modules install user
pos-cli modules download user
Then deploy your project again:
pos-cli deploy staging
At this point, your instance includes all necessary endpoints: login, registration, password reset, two-factor authentication, OAuth handlers, and more. You will connect these pages to your application later through navigation.
Step 6: Configure Common Styling
The Common Styling module is installed automatically as a dependency of the User Module. However, for its design system to take effect, you need to activate and configure it in your main layout.
Common Styling provides the base CSS, form styling, and UI components used across all platformOS modules, including the pages that come with the User Module. By loading it in your layout, you ensure that the login, registration, and profile pages look consistent and match the styling of your own application.
Open your application layout and replace its content with the following:
app/views/layouts/application.liquid
<!DOCTYPE html>
<html class="pos-app">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<meta content="authenticity_token" name="csrf-param">
<meta content="{{ form_authenticity_token }}" name="csrf-token">
{% comment %} Default platformOS styles {% endcomment %}
{% render 'modules/common-styling/init' %}
<link rel="stylesheet" href="{{ 'modules/user/style/pos-user-form.css' | asset_url }}">
{% comment %} Custom project styles {% endcomment %}
<link rel="stylesheet" href="{{ 'style/app.css' | asset_url }}">
<script>
if (typeof window.pos !== 'object') {
window.pos = {};
window.pos.modules = {};
window.pos.translations = {};
}
</script>
<title>User Management Application | platformOS</title>
</head>
<body>
{{ content_for_layout }}
{% liquid
render 'modules/common-styling/toasts'
%}
<script src="{{ 'scripts/app.js' | asset_url }}"></script>
</body>
</html>
Save and deploy (or sync) the changes.
For advanced configuration and customization options, refer to the Common Styling documentation, or visit the built-in /style-guide page on your instance to explore all available components.
Step 7: Create the Homepage
Now that the environment is set up, update the homepage of your project. The file already exists, so open it and replace its content with the following:
app/views/pages/index.liquid
<h2 class="pos-heading-2">Example platformOS User Management Application</h2>
<p>
This example application demonstrates the core authentication features provided
by the platformOS User Module. It includes the necessary pages and flows for
registering a new user, logging in and out, updating account information, and
exploring the default endpoints that come with the module.
</p>
Deploy your changes and reload your instance to confirm the page loads correctly. If Common Styling is configured correctly, the heading and text should display using the default typography and spacing:
