lando-ui is a Flask-based web application that serves as a graphical user interface to lando-api. It is separate from the latter to isolate the logic of automatic landings from its interface(s).
Please read the general Conduit contribution guidelines before getting into the specifics of lando-ui.
- docker and docker-compose (on OS X and Windows you should use the full Docker for Mac or Docker for Windows systems, respectively)
pyinvokecurrently has no backwards-compatibility guarantees, it is suggested that you install exactly version 0.21.0 via
pip install invoke==0.21.0or
pip install --user invoke==0.21.0.
- You can use a virtualenv instead of installing it system wide, but you should create the virtualenv outside of the lando-ui source directory so that the linter doesn't check the virtualenv files.
- If you are running Windows, you will need a special file in your user
.invoke.yml. It should contain the following:
run: shell: C:\Windows\System32\cmd.exe
As Flask requires a real server name to use session cookies, you
will need to make an entry in your host config or a local DNS server.
On Linux and MacOS, the hosts file is located at
Windows, it is located at
The format is the same on all three OSs, requiring the addition of the
If you are using Docker Machine, you will need to replace
127.0.0.1 with the IP of your Docker Machine host. Note that you
127.0.0.1 on Windows if you use the full Docker for Windows
After updating your hosts file (no reboot is required), in a terminal
docker-compose up in the root lando-ui directory. On
Windows, we recommend using Git Bash, which provides a Linux-like
After a while, you will see within docker-compose's output a line like this:
lando-ui_1 | * Running on http://0.0.0.0:7777/ (Press CTRL+C to quit)
At this point, you should be able to visit
http://lando-ui.test:7777/ in your browser.
Use with lando-api
lando-ui requires an instance of lando-api to talk to in order to do
anything interesting. The default configuration sets the location of
http://lando-api.test:8888, which is the default for a
local installation of lando-api.
Running the tests
lando-ui's tests use
pytest-flask, executed within a
Docker container. The tests are located in
./tests/. You can run
all of them via
$ invoke test
Subsets of the tests, e.g. linters, and other commands are also available. Run
invoke -l to see all tasks.
Setting up Auth0
We use Auth0 to authenticate application users. You will need to sign up for a personal Auth0 account to manually test code landing workflows and protected pages.
After signing up you must create an Auth0 Application for lando-ui testing. See the Auth0 docs for details on how to do this.
Once you have created the lando-ui Application in your Auth0 management dashboard, go
Application page and configure the following:
Client Type: Regular Web Application
Token Endpoint Authentication Method: POST
Allowed Callback URLs: http://lando-ui.test:7777/redirect_uri, http://lando-ui.test/redirect_uri
Allowed Web Origins: (leave blank)
Allowed Logout URLs: http://lando-ui.test:7777/signout, http://lando-ui.test/signout
Allowed Origins (CORS): (leave blank)
Show Advanced Settingson the
Client Settingspage, then select the
JsonWebToken Signature Algorithm: HS256
Create an Auth0 API (click
API in the Auth0 left side bar)
Signing Algorithm: RS256
- Go to the new API's
Permissionstab and add a permission:
Description: Bearer has authorized Lando to land code on their behalf
docker-compose.override.yml file in repository's root directory with
version: '2' services: lando-ui: environment: - OIDC_DOMAIN=your personal auth0 domain with no http prefix - OIDC_CLIENT_ID=your Auth0 Client ID (from the Client Settings page) - OIDC_CLIENT_SECRET=your Auth0 Client Secret (from the Client Settings page) - LANDO_API_OIDC_IDENTIFIER=the identifier you gave to the API you made (e.g. http://lando-api.test)
Restart the lando-ui service with docker-compose.
To log in to your new service you must create a User account.
http://lando-ui.test:7777/in your browser. You should see the Lando front page as a signed-out or anonymous user would see it.
- Click the "Log in" button on the top navigation bar and you will be presented with the lando-ui sign-in page.
- On the lando-ui sign-in page click the "Sign Up" tab.
- Follow the sign-up instructions. (Using the "Sign Up With Google" button makes this task trivial.)
You should now be able to use the lando-ui "Log in" and "Log out" buttons.
How do I make the Land button work?
You need to change some settings in the lando-api service to make the
Land button in lando-ui function. See the
environment variables in the lando-api docker-compose.yml for details.
Developing and testing against Conduit Suite
Sometimes it's necessary to use a more realistic infrastructure setup to test template rendering, frontend/backend interactions, and to test with special case data such as secure revisions. We can achieve this by running our Lando UI project code inside the Conduit Suite project's development environment. Conduit Suite provides all of the collaborating services (Lando API, Phabricator, BMO) necessary for Lando UI to function as the real service would.
First set up Auth0 according to the Setting up Auth0 instruction section above.
Next follow the Conduit Suite generic setup instructions. Verify that you can run the Suite project from in it's own project directory with
docker-compose up. Verify that you can use the
firefox-proxyscript in the Suite project's root directory to access the Suite's bundled copy of Lando UI.
Once you have the Suite running with it's bundled copy of Lando UI you can modify it's
docker-composeconfiguration to build and run lando-ui from the sources in the project directory you have been hacking in. Instructions are in the Conduit Suite project README.