https://github.com/interline-io/transitland-server
Transitland Server
https://github.com/interline-io/transitland-server
golang graphql-api gtfs gtfs-realtime rest-api transit transitland transportation
Last synced: about 2 months ago
JSON representation
Transitland Server
- Host: GitHub
- URL: https://github.com/interline-io/transitland-server
- Owner: interline-io
- License: other
- Created: 2021-07-16T00:32:17.000Z (about 4 years ago)
- Default Branch: main
- Last Pushed: 2025-08-22T02:46:13.000Z (about 2 months ago)
- Last Synced: 2025-08-22T03:47:51.373Z (about 2 months ago)
- Topics: golang, graphql-api, gtfs, gtfs-realtime, rest-api, transit, transitland, transportation
- Language: Go
- Homepage: https://pkg.go.dev/github.com/interline-io/transitland-server
- Size: 10.3 MB
- Stars: 8
- Watchers: 2
- Forks: 4
- Open Issues: 2
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# Interline Transitland Server
[](https://godoc.org/github.com/interline-io/transitland-server) 
## Table of Contents
- [Installation](#installation)
- [Usage](#usage)
- [Usage as a web service](#usage-as-a-web-service)
- [Development](#development)
- [Licenses](#licenses)
## Installation
`cd cmd/tlserver && go install .`
## Usage
The resulting [`tlserver`](docs/cli/tlserver.md) binary includes several core commands from `transitland-lib` and adds the `server` command.
The main subcommands are:
* [tlserver server](docs/cli/tlserver_server.md) - Run transitland server
* [tlserver version](docs/cli/tlserver_version.md) - Program version and supported GTFS and GTFS-RT versions
* [tlserver fetch](docs/cli/tlserver_fetch.md) - Fetch GTFS data and create feed versions
* [tlserver import](docs/cli/tlserver_import.md) - Import feed versions
* [tlserver sync](docs/cli/tlserver_sync.md) - Sync DMFR files to database
* [tlserver unimport](docs/cli/tlserver_unimport.md) - Unimport feed versions
* [tlserver rebuild-stats](docs/cli/tlserver_rebuild-stats.md) - Rebuild statistics for feeds or specific feed versions
## Usage as a web service
To start the server with the REST API endpoints, GraphQL API endpoint, GraphQL explorer UI, and image generation endpoints:
```
tlserver server --dburl "postgres://your_host/your_database"
```
Alternatively, the database connection string can be specified using `TL_DATABASE_URL` environment variable. For local development environments, you will usually need to add `?sslmode=disable` to the connection string.
Open http://localhost:8080/ in your web browser to see the GraphQL browser, or use the endpoints at `/query` or `/rest/...`
The REST API is documented with OpenAPI 3.0:
- **Interactive documentation**: http://localhost:8080/rest/openapi.json
- **Static schema**: [docs/openapi/rest.json](docs/openapi/rest.json)
The "example" server instance configured by the `tlserver` command runs without authentication or authorization. Auth configuration is beyond the scope of this example command but can be added by configuring the server in your own package and adding HTTP middlewares to set user context and permissions data. You can use `cmd/tlserver/main.go` as an example to get started; it uses only public APIs from this package. (Earlier versions of `tlserver` included more built-in auth middlewares, but in our experience these are almost always custom per-installation, and were removed from this repo.) Additionally, this example server configuration exposes Go profiler endpoints on `/debug/pprof/...`.
## Development
1. Install `go install -tags 'postgres' github.com/golang-migrate/migrate/v4/cmd/migrate@latest`
2. On macOS, you will need the GNU timeout command: `brew install coreutils`
3. You will also need GDAL tools for importing reference data sets: `apt-get install gdal-bin`, or `brew install gdal-bin`, etc.
4. Check out `github.com/interline-io/transitland-lib` which contains the necessary schema and migrations.
5. Set `TL_TEST_SERVER_DATABASE_URL` to the connection string to a test database
- e.g. `postgresql://localhost:5432/tlv2_test_server?sslmode=disable`
- You must also set `PGHOST=localhost`, `PGDATABASE=tlv2_test_server`, etc., to match this url
- This requirement may be removed in the future
1. Initialize test fixtures: `./testdata/server/test_setup.sh`
- This will create the `tlv2_test_server` database in postgres
- Will halt with an error (intentionally) if this database already exists
- Runs migrations in `transitland-lib/schema/postgres/migrations`
- Unpacks and imports the Natural Earth datasets bundled with `transitland-lib`
- Builds and installs the `cmd/tlserver` command
- Sets up test feeds contained in `testdata/server/server-test.dmfr.json`
- Fetches and imports feeds contained in `testdata/server/gtfs`
- Creates additional fixtures defined in `testdata/server/test_supplement.pgsql`
- Note that temporary files will be created in `testdata/server/tmp`; these are excluded in `.gitignore`
2. Optional: Set `TL_TEST_REDIS_URL` to run some GBFS tests
3. Optional: Set `TL_TEST_FGA_ENDPOINT` to a running [OpenFGA](https://github.com/openfga/openfga) server to run authorization tests
4. Run all tests with `go test -v ./...`
Test cases generally run within transactions; you do not need to regenerate the fixtures unless you are testing migrations or changes to data import functionality.
## Licenses
`transitland-server` is released under a "dual license" model:
- open-source for use by all under the [GPLv3](LICENSE) license
- also available under a flexible commercial license from [Interline](mailto:info@interline.io)