docker

Documentation

Index

• Variables
• type Environment
  • func New(id string, m *Metadata, c *environment.Configuration) (*Environment, error)
  • func (e *Environment) Attach(ctx context.Context) error
  • func (e *Environment) Config() *environment.Configuration
  • func (e *Environment) ContainerInspect(ctx context.Context) (types.ContainerJSON, error)
  • func (e *Environment) Create() error
  • func (e *Environment) Destroy() error
  • func (e *Environment) Events() *events.Bus
  • func (e *Environment) Exists() (bool, error)
  • func (e *Environment) ExitState() (uint32, bool, error)
  • func (e *Environment) InSituUpdate() error
  • func (e *Environment) IsAttached() bool
  • func (e *Environment) IsRunning(ctx context.Context) (bool, error)
  • func (e *Environment) OnBeforeStart(ctx context.Context) error
  • func (e *Environment) Readlog(lines int) ([]string, error)
  • func (e *Environment) SendCommand(c string) error
  • func (e *Environment) SetImage(i string)
  • func (e *Environment) SetLogCallback(f func([]byte))
  • func (e *Environment) SetState(state string)
  • func (e *Environment) SetStopConfiguration(c remote.ProcessStopConfiguration)
  • func (e *Environment) SetStream(s *types.HijackedResponse)
  • func (e *Environment) Start(ctx context.Context) error
  • func (e *Environment) State() string
  • func (e *Environment) Stop(ctx context.Context) error
  • func (e *Environment) Terminate(ctx context.Context, signal os.Signal) error
  • func (e *Environment) Type() string
  • func (e *Environment) Uptime(ctx context.Context) (int64, error)
  • func (e *Environment) WaitForStop(ctx context.Context, duration time.Duration, terminate bool) error
• type Metadata

Variables

var ErrNotAttached = errors.Sentinel("not attached to instance")

Types

type Environment

type Environment struct {

	// The public identifier for this environment. In this case it is the Docker container
	// name that will be used for all instances created under it.
	Id string

	// The environment configuration.
	Configuration *environment.Configuration
	// contains filtered or unexported fields
}

func New

func New(id string, m *Metadata, c *environment.Configuration) (*Environment, error)

New creates a new base Docker environment. The ID passed through will be the ID that is used to reference the container from here on out. This should be unique per-server (we use the UUID by default). The container does not need to exist at this point.

func (*Environment) Attach

func (e *Environment) Attach(ctx context.Context) error

Attach attaches to the docker container itself and ensures that we can pipe data in and out of the process stream. This should always be called before you have started the container, but after you've ensured it exists.

Calling this function will poll resources for the container in the background until the container is stopped. The context provided to this function is used for the purposes of attaching to the container, a second context is created within the function for managing polling.

func (*Environment) Config

func (e *Environment) Config() *environment.Configuration

Config returns the environment configuration allowing a process to make modifications of the environment on the fly.

func (*Environment) ContainerInspect

func (e *Environment) ContainerInspect(ctx context.Context) (types.ContainerJSON, error)

ContainerInspect is a rough equivalent of Docker's client.ContainerInspect() but re-written to use a more performant JSON decoder. This is important since a large number of requests to this endpoint are spawned by Wings, and the standard "encoding/json" shows its performance woes badly even with single containers running.

func (*Environment) Create

func (e *Environment) Create() error

Create creates a new container for the server using all the data that is currently available for it. If the container already exists it will be returned.

func (*Environment) Destroy

func (e *Environment) Destroy() error

Destroy will remove the Docker container from the server. If the container is currently running it will be forcibly stopped by Docker.

func (*Environment) Events

func (e *Environment) Events() *events.Bus

Events returns an event bus for the environment.

func (*Environment) Exists

func (e *Environment) Exists() (bool, error)

Exists determines if the container exists in this environment. The ID passed through should be the server UUID since containers are created utilizing the server UUID as the name and docker will work fine when using the container name as the lookup parameter in addition to the longer ID auto-assigned when the container is created.

func (*Environment) ExitState

func (e *Environment) ExitState() (uint32, bool, error)

ExitState returns the container exit state, the exit code and whether or not the container was killed by the OOM killer.

func (*Environment) InSituUpdate

func (e *Environment) InSituUpdate() error

InSituUpdate performs an in-place update of the Docker container's resource limits without actually making any changes to the operational state of the container. This allows memory, cpu, and IO limitations to be adjusted on the fly for individual instances.

func (*Environment) IsAttached

func (e *Environment) IsAttached() bool

IsAttached determines if this process is currently attached to the container instance by checking if the stream is nil or not.

func (*Environment) IsRunning

func (e *Environment) IsRunning(ctx context.Context) (bool, error)

IsRunning determines if the server's docker container is currently running. If there is no container present, an error will be raised (since this shouldn't be a case that ever happens under correctly developed circumstances).

You can confirm if the instance wasn't found by using client.IsErrNotFound from the Docker API.

@see docker/client/errors.go

func (*Environment) OnBeforeStart

func (e *Environment) OnBeforeStart(ctx context.Context) error

OnBeforeStart run before the container starts and get the process configuration from the Panel. This is important since we use this to check configuration files as well as ensure we always have the latest version of an egg available for server processes.

This process will also confirm that the server environment exists and is in a bootable state. This ensures that unexpected container deletion while Wings is running does not result in the server becoming un-bootable.

func (*Environment) Readlog

func (e *Environment) Readlog(lines int) ([]string, error)

Readlog reads the log file for the server. This does not care if the server is running or not, it will simply try to read the last X bytes of the file and return them.

func (*Environment) SendCommand

func (e *Environment) SendCommand(c string) error

SendCommand sends the specified command to the stdin of the running container instance. There is no confirmation that this data is sent successfully, only that it gets pushed into the stdin.

func (*Environment) SetImage

func (e *Environment) SetImage(i string)

func (*Environment) SetLogCallback

func (e *Environment) SetLogCallback(f func([]byte))

func (*Environment) SetState

func (e *Environment) SetState(state string)

SetState sets the state of the environment. This emits an event that server's can hook into to take their own actions and track their own state based on the environment.

func (*Environment) SetStopConfiguration

func (e *Environment) SetStopConfiguration(c remote.ProcessStopConfiguration)

SetStopConfiguration sets the stop configuration for the environment.

func (*Environment) SetStream

func (e *Environment) SetStream(s *types.HijackedResponse)

SetStream sets the current stream value from the Docker client. If a nil value is provided we assume that the stream is no longer operational and the instance is effectively offline.

func (*Environment) Start

func (e *Environment) Start(ctx context.Context) error

Start will start the server environment and begins piping output to the event listeners for the console. If a container does not exist, or needs to be rebuilt that will happen in the call to OnBeforeStart().

func (*Environment) State

func (e *Environment) State() string

func (*Environment) Stop

func (e *Environment) Stop(ctx context.Context) error

Stop stops the container that the server is running in. This will allow up to 30 seconds to pass before the container is forcefully terminated if we are trying to stop it without using a command sent into the instance.

You most likely want to be using WaitForStop() rather than this function, since this will return as soon as the command is sent, rather than waiting for the process to be completed stopped.

func (*Environment) Terminate

func (e *Environment) Terminate(ctx context.Context, signal os.Signal) error

Terminate forcefully terminates the container using the signal provided.

func (*Environment) Type

func (e *Environment) Type() string

func (*Environment) Uptime

func (e *Environment) Uptime(ctx context.Context) (int64, error)

Uptime returns the current uptime of the container in milliseconds. If the container is not currently running this will return 0.

func (*Environment) WaitForStop

func (e *Environment) WaitForStop(ctx context.Context, duration time.Duration, terminate bool) error

WaitForStop attempts to gracefully stop a server using the defined stop command. If the server does not stop after seconds have passed, an error will be returned, or the instance will be terminated forcefully depending on the value of the second argument.

Calls to Environment.Terminate() in this function use the context passed through since we don't want to prevent termination of the server instance just because the context.WithTimeout() has expired.

type Metadata

type Metadata struct {
	Image string
	Stop  remote.ProcessStopConfiguration
}