0
# Dagster Webserver
1

2
A web server implementation for the Dagster UI that provides a browser-based interface for data orchestration and pipeline management. The webserver serves as the primary interface between users and Dagster instances, offering GraphQL APIs, asset reporting capabilities, and comprehensive web UI functionality.
3

4
## Package Information
5

6
- **Package Name**: dagster-webserver
7
- **Package Type**: pypi
8
- **Language**: Python
9
- **Installation**: `pip install dagster-webserver`
10
- **Version**: 1.11.8
11

12
## Core Imports
13

14
```python
15
from dagster_webserver.app import create_app_from_workspace_process_context
16
from dagster_webserver.cli import host_dagster_ui_with_workspace_process_context, create_dagster_webserver_cli
17
from dagster_webserver.webserver import DagsterWebserver
18
from dagster_webserver.version import __version__
19
```
20

21
## Basic Usage
22

23
### Starting the Webserver (CLI)
24

25
```python
26
# Command line usage
27
dagster-webserver --host 0.0.0.0 --port 3000 --workspace-file workspace.yaml
28
```
29

30
### Programmatic Usage
31

32
```python
33
from dagster import DagsterInstance
34
from dagster._core.workspace.context import WorkspaceProcessContext
35
from dagster_webserver.app import create_app_from_workspace_process_context
36
import uvicorn
37

38
# Create workspace context
39
instance = DagsterInstance.get()
40
with WorkspaceProcessContext(instance) as workspace_context:
41
    # Create ASGI app
42
    app = create_app_from_workspace_process_context(
43
        workspace_context,
44
        path_prefix="",
45
        live_data_poll_rate=2000
46
    )
47
    
48
    # Run with uvicorn
49
    uvicorn.run(app, host="127.0.0.1", port=3000)
50
```
51

52
## Architecture
53

54
The dagster-webserver is built on a layered architecture:
55

56
- **CLI Layer**: Command-line interface for server management and configuration
57
- **Application Layer**: ASGI application factory and routing logic  
58
- **GraphQL Layer**: GraphQL server implementation with HTTP and WebSocket support
59
- **Asset Reporting Layer**: HTTP endpoints for external asset event reporting
60
- **Web UI Layer**: Static file serving and HTML template rendering
61
- **Debug Layer**: Specialized debugging tools and ephemeral instance support
62

63
This design enables flexible deployment scenarios, from simple CLI usage to complex programmatic integration with custom middleware and routing.
64

65
## Capabilities
66

67
### Command Line Interface
68

69
Primary interface for starting and configuring the dagster webserver, including production deployments, development environments, and debugging scenarios.
70

71
```python { .api }
72
def main(): ...
73
def host_dagster_ui_with_workspace_process_context(
74
    workspace_process_context: IWorkspaceProcessContext,
75
    host: Optional[str] = None,
76
    port: Optional[int] = None,
77
    path_prefix: str = "",
78
    log_level: str = "warning",
79
    live_data_poll_rate: Optional[int] = None
80
): ...
81
def create_dagster_webserver_cli() -> click.Command: ...
82
```
83

84
[CLI Commands](./cli.md)
85

86
### Application Factory
87

88
Core functionality for creating ASGI applications from workspace contexts, enabling programmatic webserver integration and custom deployment scenarios.
89

90
```python { .api }
91
def create_app_from_workspace_process_context(
92
    workspace_process_context: IWorkspaceProcessContext,
93
    path_prefix: str = "",
94
    live_data_poll_rate: Optional[int] = None,
95
    **kwargs
96
) -> Starlette: ...
97
```
98

99
[Application Factory](./application.md)
100

101
### GraphQL Server
102

103
Complete GraphQL server implementation with HTTP and WebSocket support, providing the core API interface for the Dagster UI and external integrations.
104

105
```python { .api }
106
class DagsterWebserver(GraphQLServer[BaseWorkspaceRequestContext]): ...
107
class GraphQLServer(ABC, Generic[TRequestContext]): ...
108
```
109

110
[GraphQL Server](./graphql.md)
111

112
### Asset Reporting
113

114
HTTP endpoints for external systems to report asset events directly to Dagster instances, enabling integration with external data pipelines and monitoring systems.
115

116
```python { .api }
117
async def handle_report_asset_materialization_request(
118
    context: BaseWorkspaceRequestContext,
119
    request: Request
120
) -> JSONResponse: ...
121
async def handle_report_asset_check_request(
122
    context: BaseWorkspaceRequestContext,
123
    request: Request
124
) -> JSONResponse: ...
125
async def handle_report_asset_observation_request(
126
    context: BaseWorkspaceRequestContext,
127
    request: Request
128
) -> JSONResponse: ...
129
```
130

131
[Asset Reporting](./asset-reporting.md)
132

133
### Debug Tools
134

135
Specialized debugging functionality for loading debug export files and running webserver instances with ephemeral data for troubleshooting and development.
136

137
```python { .api }
138
class WebserverDebugWorkspaceProcessContext(IWorkspaceProcessContext): ...
139
def webserver_debug_command(input_files, port): ...
140
```
141

142
[Debug Tools](./debug.md)
143

144
## Types
145

146
```python { .api }
147
# Core webserver class
148
class DagsterWebserver(GraphQLServer[BaseWorkspaceRequestContext], Generic[T_IWorkspaceProcessContext]):
149
    def __init__(
150
        self,
151
        process_context: T_IWorkspaceProcessContext,
152
        app_path_prefix: str = "",
153
        live_data_poll_rate: Optional[int] = None,
154
        uses_app_path_prefix: bool = True
155
    ): ...
156

157
# Abstract GraphQL server base
158
class GraphQLServer(ABC, Generic[TRequestContext]):
159
    def __init__(self, app_path_prefix: str = ""): ...
160

161
# Debug workspace context  
162
class WebserverDebugWorkspaceProcessContext(IWorkspaceProcessContext):
163
    def __init__(self, instance: DagsterInstance): ...
164

165
# GraphQL WebSocket protocol constants
166
class GraphQLWS(str, Enum):
167
    PROTOCOL = "graphql-ws"
168
    CONNECTION_INIT = "connection_init"
169
    CONNECTION_ACK = "connection_ack"
170
    CONNECTION_ERROR = "connection_error"
171
    CONNECTION_TERMINATE = "connection_terminate"
172
    CONNECTION_KEEP_ALIVE = "ka"
173
    START = "start"
174
    DATA = "data"
175
    ERROR = "error"
176
    COMPLETE = "complete"
177
    STOP = "stop"
178

179
# Asset reporting parameter classes
180
class ReportAssetMatParam:
181
    asset_key = "asset_key"
182
    data_version = "data_version"
183
    metadata = "metadata"
184
    description = "description"
185
    partition = "partition"
186

187
class ReportAssetCheckEvalParam:
188
    asset_key = "asset_key"
189
    check_name = "check_name"
190
    metadata = "metadata"
191
    severity = "severity"
192
    passed = "passed"
193

194
class ReportAssetObsParam:
195
    asset_key = "asset_key"
196
    data_version = "data_version"
197
    metadata = "metadata"
198
    description = "description"
199
    partition = "partition"
200
```
201

202
## Constants
203

204
```python { .api }
205
# Default configuration values
206
DEFAULT_WEBSERVER_HOST = "127.0.0.1"
207
DEFAULT_WEBSERVER_PORT = 3000
208
DEFAULT_DB_STATEMENT_TIMEOUT = 15000  # milliseconds
209
DEFAULT_POOL_RECYCLE = 3600  # seconds
210
DEFAULT_POOL_MAX_OVERFLOW = 20
211
WEBSERVER_LOGGER_NAME = "dagster-webserver"
212

213
# Version information (imported from version.py)
214
from dagster_webserver.version import __version__
215
```