Work in progress
Note that there is a local .tool-versions in project root. For the following setup to work, we need to
-
Install asdf
-
Run the following to install all dependencies in .tool-versions
asdf install
-
Install icu4c
brew install icu4c
icu4c installed by brew is not globally visible by default, so you have to ensure your shell has the following in effect
export PKG_CONFIG_PATH="$(brew --prefix)/opt/icu4c/lib/pkgconfig"
To avoid doing the above every time you open a new shell, you may want to add it to your shell initialization script such as ~/.profile
, ~/.bash_profile
, etc.
- Install libvips
brew install vips
libvips on macOS requires -Xpreprocessor
to build.
Run the following to tell Cgo.
export CGO_CFLAGS_ALLOW="-Xpreprocessor"
- Install libmagic
brew install libmagic
Run the following to tell Cgo where to find libmagic. Preferably you add it to your shell startup script.
export CGO_CFLAGS="-I$(brew --prefix)/include"
export CGO_LDFLAGS="-L$(brew --prefix)/lib"
- Run
make vendor
-
Setup environment variables:
cp .env.example .env
-
Initialize app
To generate the necessary config and secret yaml file, run
go run ./cmd/authgear init authgear.yaml --output ./var/authgear.yaml go run ./cmd/authgear init authgear.secrets.yaml --output ./var/authgear.secrets.yaml
then follow the instructions. For database URL and schema, use the following,
DATABASE_URL=postgres://[email protected]:5432/postgres?sslmode=disable DATABASE_SCHEMA=app
-
Setup
.localhost
domainFor cookie to work properly, you need to use
portal.localhost:8000
to access the portal.accounts.portal.localhost:3000
to access the main server.
You can either do this by editing
/etc/hosts
or installdnsmasq
. -
(Optional) To use db as config source.
- Update
.env
to changeCONFIG_SOURCE_TYPE=database
- Setup config source in db
go run ./cmd/portal internal setup-portal ./var/ \ --default-authgear-domain=accounts.localhost \ --custom-authgear-domain=accounts.portal.localhost \
- Update
-
Start the db container
docker-compose up -d db
-
Create a schema:
Run the following SQL command with command line to such as
psql
or DB viewer such asPostico
CREATE SCHEMA app;
-
Apply database schema migrations:
make sure the db container is running
go run ./cmd/authgear database migrate up --database-url='postgres://[email protected]:5432/postgres?sslmode=disable' --database-schema=app
To create new migration:
# go run ./cmd/authgear database migrate new <migration name>
go run ./cmd/authgear database migrate new add user table
If you are testing external OAuth provider, you must enable TLS.
- Cookie is only included in third party redirect if it has SameSite=None attribute.
- Cookie with SameSite=None attribute without Secure attribute is rejected.
To setup HTTPS easily, you can use mkcert
# Install mkcert.
brew install mkcert
# Install the root CA into Keychain Access.
mkcert -install
# Create TLS certificate and private key with the given host.
mkcert -cert-file tls-cert.pem -key-file tls-key.pem localhost 127.0.0.1 ::1
One caveat is HTTP redirect to HTTPS is not supported, you have to type in https in the browser address bar manually.
docker-compose up -d
Then run the command
# in project root
go run ./cmd/authgear start
To run graphql server
# in project root
go run ./cmd/portal start
Some features (e.g. custom domains) requires multi-tenant mode to work properly. To setup multi-tenant mode:
-
Setup local mock Kubernetes servers:
cd hack/kube-apiserver docker-compose up -d
-
Install cert manager CRDs:
kubectl --kubeconfig=hack/kube-apiserver/.kubeconfig apply --validate=false -f https://github.com/jetstack/cert-manager/releases/download/v1.3.1/cert-manager.crds.yaml
-
Bootstrap Kubernetes resources:
kubectl --kubeconfig=hack/kube-apiserver/.kubeconfig apply -f hack/k8s-manifest.yaml
-
Enable multi-tenant mode in Authgear & portal server: refer to
.env.example
for example environment variables to set
graphql must be 15 otherwise npm run gentype
will fail.
When graphql is ^15.0.0, we will see missing peer dependency of graphql@^14.0.0
See apollographql/apollo-tooling#2232
apollo-language-server may include its own graphql.
That copy must be removed manually from package-lock.json,
otherwise, npm run gentype
will fail.
@monaco-editor/react>=4 is slow in our usage. We need to adjust how we use it when we upgrade.
As useBlocker
is removed since react-router-domv6.0.0-beta.7 and have no promise which version will
come back, we introduce the custom useBlocker
hook by referencing the last commit which this hook
still exist.
See https://github.com/remix-run/react-router/commit/256cad70d3fd4500b1abcfea66f3ee622fb90874
When Parcel cannot resolve nodejs globals such as process
and Buffer
,
it installs them for us.
But we do not want to do that.
The workaround is to add alias
to package.json.
See parcel-bundler/parcel#7697.
With newer version (>=8.3.1) of npm and Nodejs 16, there is a bug that
platform-specific optional dependencies not being included in package-lock.json
.
Once these dependencies are not installed, the portal image cannot be built.
As parcel
required @parcel/css
, and @parcel/css
required some of these dependencies,
at this moment this bug will occur, the workaround is to add
@parcel/css
, lmdb
and msgpackr-extract
to the package.json
See npm/cli#4828
We need to set up environment variables for Authgear servers and portal server.
Make a copy of .env.example
as .env
, and update it if necessary.
- Install dependencies
npm install
- Run development server
npm start
This command should start a web development server on port 1234.
- Configure authgear.yaml
We need the following authgear.yaml
to setup authgear for the portal.
id: accounts # Make sure the ID matches AUTHGEAR_APP_ID environment variable.
http:
# Make sure this matches the host used to access main Authgear server.
public_origin: "http://accounts.portal.localhost:3000"
allowed_origins:
# The SDK uses XHR to fetch the OAuth/OIDC configuration,
# So we have to allow the origin of the portal.
# For simplicity, allow all origin for development setup.
- "*"
oauth:
clients:
# Create a client for the portal.
# Since we assume the cookie is shared, there is no grant nor response.
- name: Portal
client_id: portal
# Note that the trailing slash is very important here
# URIs are compared byte by byte.
redirect_uris:
# This redirect URI is used by the portal development server.
- "http://portal.localhost:8000/oauth-redirect"
# This redirect URI is used by the portal production build.
- "http://portal.localhost:8010/oauth-redirect"
# This redirect URI is used by the iOS and Android demo app.
- "com.authgear.example://host/path"
# This redirect URI is used by the React Native demo app.
- "com.authgear.example.rn://host/path"
post_logout_redirect_uris:
# This redirect URI is used by the portal development server.
- "http://portal.localhost:8000/"
# This redirect URI is used by the portal production build.
- "http://portal.localhost:8010/"
grant_types: []
response_types: ["none"]
FIXME
: Should be fixed as soon as possibleTODO
: Should be done when someone really needs it.OPTIMIZE
: Should be done when it really becomes a performance issue.SECURITY
: Known potential security issue.
- Free email provider domains list provided by: https://gist.github.com/tbrianjones/5992856/
- This product includes GeoLite2 data created by MaxMind, available from https://www.maxmind.com
# Create release tag when deploying to staging or production
# For staging, prefix the tag with `staging-`. e.g. staging-2021-05-06.0
# For production, no prefix is needed. e.g 2021-05-06.0
# If there are more than 1 release in the same day, increment the last number by 1
git tag -a YYYY-MM-DD.0
# Show the logs summary
make logs-summary A=<previous tag> B=<current tag>
Various files in this project have versioned dependencies.
- The go directive in go.mod
- The dependencies listed in go.mod
- The tool versions listed in .tool-versions
- The versions appearing in ./github/workflows/ci.yaml
- The FROM directives in ./cmd/authgear/Dockerfile
- The FROM directives in ./cmd/portal/Dockerfile
- The dependencies in ./authui/package.json
- The dependencies in ./portal/package.json
- The dependencies in ./scripts/npm/package.json
- Note that you cannot simply upgrade
tzdata
because the version must match that of the server. - You can find out the server version by going into the container and run
apt list --installed
. - The version of Debian bullseye is
2021a
, which correspond to[email protected]
.
- Note that you cannot simply upgrade
- The cropperjs type definition in ./authui/src